Skip to main content

Network Troubleshooting

This page covers common issues with the Atrium Agent, RADIUS authentication, and session termination.

Agent won't connect to the server​

Symptom: Agent logs show WebSocket connection errors. Dashboard shows "Disconnected" for the site.

Check:

  1. Verify ATRIUM_SERVER_URL is correct (must be wss:// for TLS connections).
  2. Verify the mTLS certificates are valid and not expired (openssl x509 -in cert.pem -noout -dates).
  3. Verify the Agent can reach the server: curl -v https://<server-url>/health from the Agent host.
  4. Check that the certificate's tenant_id and site_id match the ATRIUM_TENANT_ID and ATRIUM_SITE_ID environment variables.

Visitors can't connect to WiFi​

Symptom: Visitor enters credentials on their device, connection fails.

Step-by-step diagnosis:

  1. Is the Agent running? Check docker ps and Agent logs.
  2. Is the Agent connected to the server? Check the dashboard agent status. If disconnected, vouchers created during disconnection won't reach the Agent.
  3. Does the voucher exist on the Agent? Agent logs show voucher.create commands. If the Agent is connected but no voucher appears, check the visit status — the voucher is only created at check-in.
  4. Is the WiFi controller pointing to the Agent? Verify RADIUS server configuration on the WiFi controller.
  5. Shared secret match? A RADIUS shared secret mismatch causes silent failures. The controller receives an undecryptable response and drops it. Double-check the secret on both sides.
  6. Port reachability? Verify UDP 1812 is open from the WiFi controller to the Agent.

RADIUS rejects valid credentials​

Symptom: Agent logs show REJECT user="..." reason=invalid_credentials for credentials that appear correct.

Possible causes:

  • Typo in credentials. The visitor may have mistyped the password. Credentials are case-sensitive.
  • Voucher expired. Check the voucher's "valid until" timestamp. If the visit's expected departure has passed, the voucher may have been cleaned up.
  • Voucher revoked. If the visit was checked out or cancelled, the voucher is revoked. Check the visit status in the dashboard.
  • Agent out of sync. If the Agent was disconnected when the voucher was created, it won't have the voucher in its store. The Agent reconciles on reconnect — verify the Agent shows as "Connected."

Session termination fails​

Symptom: Visit ends, but the visitor's device remains connected to WiFi.

This is expected behavior in some cases. Session termination is best-effort. The firewall may not respond to CoA/DM, or the session may have already ended naturally.

Check:

  1. Agent logs: Look for termination commands and responses. A session.termination_failed event indicates the firewall didn't confirm.
  2. Firewall adapter configured? If no adapter is configured, the Agent revokes the voucher (no new connections) but doesn't attempt session termination.
  3. Firewall reachable? Verify connectivity from the Agent to the firewall (UDP 3799 for CoA/DM, HTTPS for REST APIs).
  4. Correct credentials? CoA shared secret or API key mismatch.
  5. Session identifiers available? If RADIUS Accounting isn't configured, the Agent may not have the session's Acct-Session-Id, making targeted termination unreliable.

Fallback: Even if termination fails, the voucher is revoked — the visitor can't establish new connections. The existing session will time out via the firewall's own session timeout (typically 30–60 minutes, configurable on the firewall).

Agent buffer overflow​

Symptom: Agent logs show "buffer overflow — some events were lost."

This means the Agent accumulated more than 10,000 queued events while disconnected from the server. Oldest events were dropped to prevent unbounded memory growth.

Resolution: This is usually harmless — lost events are informational (RADIUS auth events, status reports). Voucher state is reconciled on reconnect, so no functional impact. If this happens frequently, investigate the cause of prolonged Agent disconnections.