Skip to content
Documentation menu · version 0.1.0-alpha.4

Troubleshooting

Start with the logs. Single host: docker compose logs -f api (and web, caddy, postgres, coturn). Kubernetes: kubectl -n yarma logs deploy/yarma-api. Agents: journalctl -u yarma-agent (Linux), /Library/Logs/YARMA/agent.log (macOS), the Application event log and Get-Service YarmaAgent (Windows). API logs are JSON lines with a request_id that is also returned to the browser in the X-Request-Id header.

Server

The API does not start

docker compose logs api (or migrate) shows the reason. Common ones:

Message Fix
TLS is required in production, auth.cookie_key is required…, files.master_key… a required setting or secret is missing; on a single host check secrets/api.env and config/config.yaml
database.ssl_mode=disable is not allowed in production enable TLS on PostgreSQL and use verify-full (or require)
storage: … connection refused object storage unreachable or wrong files.s3_endpoint/keys; the API retries on restart
files.clamd_addr is required configure ClamAV, or set files.require_scan: false (files are then not scanned)
migration errors the database user lacks rights, or the database was restored without the yarma_app role; see backup and restore

The console shows 502 Bad Gateway

The console proxy cannot reach the API. Check that the API is running and listening (log line starting), that /api/readyz reports PostgreSQL and Redis ok, and on Kubernetes that the console trusts the API certificate (api.tlsCASecret) and the certificate names the API service.

Let's Encrypt certificate is not issued

docker compose logs caddy. TCP 80 and 443 must be reachable from the internet and the DNS name must point at the server. For internal servers use --tls-cert/--tls-key.

Sign-in fails

  • Invalid email or password for a correct password: check the organization field; it is the tenant slug given to bootstrap -tenant.
  • OIDC redirect_uri mismatch: register https://<console>/api/v1/auth/callback exactly; auth.public_url must be the public console URL plus /api.
  • Users are not created on first sign-in: their email domain must be in the provider's allowed domains.
  • A user without any role binding signs in but sees almost nothing: assign a role.
  • Repeated failures are rate limited per client IP. Behind your own load balancer, add its addresses to server.trusted_proxies so the real client IP is used.

Agents

Enrollment fails

Agent message Cause
invalid enrollment token token mistyped, expired, used up or revoked: create a new one
license does not permit enrolling more devices no license installed, or the device limit is reached (see the License page)
certificate / UnknownIssuer / name mismatch errors wrong agent-ca.crt, or the URL host is not the name in the agent-service certificate (init.sh --agents-host; Helm: pki init -hosts)
connection refused or timeout TCP 18443 blocked by a firewall or proxy; the agent needs a direct TCP connection (no TLS inspection)

Device shows offline

Check the service is running and its log. A retired device is permanently refused: enroll it again with a new token. If the server's agent CA was regenerated, every device must be re-enrolled; restore the original secrets/pki instead.

Sessions connect but show no video

  • The browser and the device must reach the TURN server on UDP/TCP 3478 and the relay range (49160–49200 UDP by default); test from both sides.
  • Behind NAT, set the public IP (external-ip in secrets/turn/turnserver.conf, init.sh --turn-ip).
  • turn.urls must name an address both sides can resolve, and YARMA_TURN_SECRET must equal the coturn static-auth-secret.
  • macOS: grant Screen Recording (and Accessibility for control) to the agent.
  • Linux: install yarma-agent-desktop; on Wayland the user must approve sharing the first time.

File transfers are rejected

Files over files.max_bytes (100 MiB default) are refused, and with files.require_scan every file must pass ClamAV: check docker compose logs clamav (the first start downloads signatures and takes several minutes).

Getting help

Collect the API log lines with the request_id, the agent log, the YARMA version (/api/version) and docker compose ps / kubectl get pods, and open an issue. Never include secrets/, .env, enrollment tokens or license keys.

Documentation for Yarma 0.1.0-alpha.4. Something unclear? .