Skip to content
Tyr

Troubleshooting

Agent

failed to load BPF program: Operation not permitted

  • Agent not running as root and missing CAP_BPF / CAP_SYS_ADMIN.
  • Fix: systemd unit needs AmbientCapabilities=CAP_BPF CAP_SYS_ADMIN … (see Linux systemd).

failed to load BPF program: Invalid argument

  • Kernel too old or CONFIG_BPF_LSM not enabled.
  • Check: cat /sys/kernel/security/lsm must contain bpf.
  • Fix: kernel 5.15+ with LSM BPF. On older distros, build a newer kernel or upgrade.

BTF not found at /sys/kernel/btf/vmlinux

  • Kernel wasn’t built with CONFIG_DEBUG_INFO_BTF=y.
  • Every modern distro ships with BTF. If you compiled your own kernel, enable it.

Agent shows offline in UI but the service is running

  • Check tyrd can reach the gRPC port: curl -v https://tyr-server:7700.
  • Check CA match: agent’s /etc/tyr/ca.pem must equal server’s /api/v1/ca.pem.
  • Check clock skew — certs reject if agent’s clock is >5 min off from server.

enrollment rejected: token consumed / expired

  • Token exceeded --max-uses or passed --expires-hours.
  • Fix: tyr enrollment-token create to mint a new one.

No events appearing

  • Is --enforce off and are there no alert rules? Audit-only + no rules = no events.
  • Test with echo test | sudo tee -a /etc/tyr-test.txt if any file-write rule is active.
  • Check journalctl -u tyr-agent | grep 'policy loaded' — policy version should be non-zero.

Server

FATAL: password authentication failed

  • DATABASE_URL credentials wrong.
  • Fix: match what’s in Postgres.

tests failed: DATABASE_URL is not set

  • Running cargo test without DB.

  • Fix:

    Terminal window
    docker compose -f deploy/docker-compose.dev.yml up -d postgres
    DATABASE_URL=postgres://tyr:tyr-dev-password@localhost:5432/tyr \
      cargo test --workspace

    Or use the rtk wrapper from the repo.

Web UI loads but API returns 404

  • TYR_WEB_DIR points at a path that doesn’t exist.
  • Fix: set it to the dir containing index.html of the built Svelte app. Inside the official image it’s /usr/share/tyr/web.

Can’t log in after fresh install

  • First start needs setup — go to /setup to create the initial admin.
  • If you already created one and lost the password, there’s no recovery today. Drop the users table and re-run /setup. (Password reset flow is a roadmap item.)

CLI

error: not logged in

  • Token missing or expired.
  • Fix: tyr login --username admin.

TLS verification errors against server

  • CLI uses the system trust store by default.
  • For self-signed server certs, either add the CA to the system store or use http:// + TYR_REST_NO_TLS=true on the server for local dev.

Docker Compose

tyr-agent container exits immediately on Mac/Windows

Expected. Docker Desktop VM can’t load host eBPF. Delete the tyr-agent: service or install the agent natively on a Linux host.

postgres restarts repeatedly

Usually permissions on the pgdata volume. docker compose down -v && docker compose up (warning: destroys data).

After docker compose pull, agent can’t reach server

Version skew is usually OK, but if you pulled the agent far ahead of the server, incompatibility can occur. Pin versions (:v0.5.2) in production.

Policy

”policy compile error” on apply

The server rejects invalid YAML or bad rules. Common causes:

  • Typo in action: — must be one of file_read, file_write, exec, net_connect, tls_connect.
  • verdict: missing or wrong value.
  • Both resource_pattern and cidr_* on the same rule.

The error message names the offending rule; check tyr policy show for the last known-good version.

Rules not taking effect

  • Is the policy assigned? tyr policy assignments to check.
  • Is the agent receiving it? journalctl -u tyr-agent | grep 'policy loaded' after assign.
  • Is the test action covered by a more specific allow above in rule order?

Use tyr policy effective <agent_id> to see what’s actually merged.

Getting help

When filing a bug, include:

  • uname -a on the affected host
  • tyrd --version and tyr-server --version
  • Last 100 lines of journalctl -u tyr-agent
  • Minimal policy to reproduce if relevant