Skip to main content

Relay Troubleshooting

Relay shows "Offline"​

  1. Check the relay service is running:
    • Linux: systemctl status tridentstack-relay
    • Windows: Get-Service TridentStackRelay
  2. Check the relay can reach the gateway: curl -v https://gateway.tridentstack.com
  3. Check relay logs:
    • Linux: journalctl -u tridentstack-relay -f
    • Windows: Event Viewer > Application log

Agents not connecting through the relay​

  1. Verify the agent was installed with --relay and --relay-ca-fingerprint flags
  2. Verify the agent can reach the relay on port 50051: nc -zv <RELAY_IP> 50051
  3. Verify the agent can reach the relay on port 8080 (for initial certificate fetch): curl http://<RELAY_IP>:8080/ca.pem
  4. Check that the fingerprint matches: compare the fingerprint in the agent's config with the one shown in Settings > Relays

Buffer depth keeps growing​

A growing buffer means the relay is receiving agent traffic but cannot deliver it upstream. This is usually a temporary network issue.

  1. Check upstream connectivity from the relay server
  2. Check relay logs for connection errors
  3. The buffer persists across relay restarts, so messages are not lost during brief outages

Relay not updating​

How a relay updates depends on how it was installed.

Native (Linux systemd) relay​

The relay self-updates from packages you publish in the Admin Portal.

  1. Verify a newer relay package is uploaded in the Admin Portal
  2. Check the relay's current version in Settings > Relays
  3. Check relay logs for update-related messages

Docker relay (including Windows and macOS)​

A Docker relay does not self-update. To move it to a new version, pull the new image and recreate the container. A docker restart alone will not do it: a running container stays pinned to the image and port mappings it was created with, so it keeps running the old version and the old ports.

docker pull ghcr.io/tridentstack/tridentstack-relay:latest
docker rm -f tridentstack-relay
# then re-run the standard docker run command from the setup guide

Your enrollment state, certificates, and message buffer survive the recreate because they live in the named volumes (tridentstack-relay-config, tridentstack-relay-data), not in the container. Recreating from the current setup command also publishes any ports the old container was missing, for example -p 8443:8443 for air-gapped enrollment.