Troubleshooting Edge Agents

Agent does not appear after registration

Symptom:You generated a registration token and started the agent process, but the agent does not show up in Settings > Edge Agents.

Likely causes: the token was not passed to the agent process correctly; the agent binary could not reach the Nuxari API on startup; the agent is running but its first check-in has not completed yet.

1. 1

   Verify the token was passed correctly

   Confirm the NUXARI_AGENT_TOKEN environment variable or --token flag is set to the exact token string copied from the UI. Even a single extra space or newline will cause the registration handshake to fail.

2. 2

   Check the agent process logs

   Run the agent in the foreground if possible and review its startup output. A successful first contact prints a message containing 'agent registered' or 'handshake complete'. An error message indicates whether the problem is a bad token, a DNS failure, or a TLS error.

3. 3

   Confirm the agent can reach api.nuxari.io on port 443

   From the host where the agent is deployed, run: curl -sv https://api.nuxari.io/health. If this fails, the network path to Nuxari is blocked. Work with your network team to open outbound HTTPS from this host.

4. 4

   Check for proxy interference

   If your environment routes HTTPS through a proxy, set the HTTPS_PROXY environment variable before starting the agent. Some corporate proxies perform TLS inspection; if the agent uses certificate pinning, the inspection will break the handshake.

5. 5

   Wait up to two minutes and refresh the agent list

   First-time registration can take up to 90 seconds to propagate to the UI. Refresh Settings > Edge Agents after two minutes before assuming the agent failed to register.

6. 6

   Re-generate the token if still not visible

   Registration tokens expire after 24 hours. If the token was generated more than 24 hours ago, delete it, generate a new one, and restart the agent with the new token.

Agent heartbeat is stale or unknown

Symptom:The agent is listed in Settings > Edge Agents but shows a status of Disconnected or a last-seen timestamp that is hours or days old.

Likely causes: the agent process has stopped; the host lost network access; a firewall rule change blocked outbound HTTPS; or the agent was suspended by the host OS.

1. 1

   Check whether the agent process is running

   On the agent host, run: ps aux | grep nuxari-agent. If the process is not listed, the agent has stopped. Restart it using the same startup command or your process manager (systemd, launchd, Windows Service).

2. 2

   Inspect the agent's own logs

   Review the agent log file (default location: /var/log/nuxari-agent/agent.log on Linux). Look for repeated connection errors, timeout messages, or authentication rejections in the last hour.

3. 3

   Test outbound HTTPS from the host

   Run: curl -sv https://api.nuxari.io/health from the agent host. If this fails and it previously worked, a firewall rule or network route has likely changed. Contact your network or security team.

4. 4

   Confirm the system clock is accurate

   Nuxari uses time-bounded tokens. If the host clock has drifted more than five minutes from UTC, heartbeat requests will be rejected with an authentication error. Check and resync the host clock using ntpdate or timedatectl.

5. 5

   Restart the agent and monitor for 5 minutes

   Restart the agent and watch for a fresh 'heartbeat sent' log line. The agent sends a heartbeat every 60 seconds by default. If the status in the UI does not update within 5 minutes, the heartbeat is still failing.

Agent shows as Revoked

Symptom:The agent in Settings > Edge Agents shows a Revoked status. The agent process may still be running but cannot connect.

1. 1

   Stop the old agent process

   On the host, stop the running agent process: systemctl stop nuxari-agent (Linux with systemd), or Stop-Service NuxariAgent (Windows). This prevents the agent from generating repeated authentication failure events.

2. 2

   Register a new agent

   In Settings > Edge Agents, click Register Agent, provide a new name, and generate a new token. The new token is valid for 24 hours.

3. 3

   Deploy the new token to the host

   Update the agent configuration on the host — replace the NUXARI_AGENT_TOKEN value with the new token. Restart the agent process.

4. 4

   Verify the new agent appears as Active

   Return to Settings > Edge Agents within 2 minutes. The new agent should show as Active with a recent last-seen timestamp. The old revoked entry can be deleted once the new agent is confirmed healthy.

Agent cannot connect to Nuxari API

Symptom:Agent logs show repeated connection errors such as "dial tcp: connection refused", "TLS handshake timeout", or "certificate verify failed".

1. 1

   Confirm outbound HTTPS to api.nuxari.io is open

   From the agent host: curl -sv https://api.nuxari.io/health. A 200 response confirms the path is open. If it times out, open port 443 outbound to api.nuxari.io in your firewall or security group.

2. 2

   Check DNS resolution

   Run: nslookup api.nuxari.io from the agent host. If DNS fails, configure the host to use a DNS resolver that can resolve public hostnames, or add a static host entry if your DNS is split-horizon.

3. 3

   Diagnose TLS certificate errors

   If the error is 'certificate verify failed', your environment may have a custom CA bundle or a TLS-inspecting proxy. Set the SSL_CERT_FILE environment variable to point to the correct CA bundle, or configure NUXARI_AGENT_SKIP_TLS_VERIFY=true only in isolated lab environments — never in production.

4. 4

   Configure proxy settings if required

   If your environment uses an HTTP proxy, set HTTPS_PROXY=http://proxy.example.com:3128 before starting the agent. Verify the proxy allows traffic to api.nuxari.io.

5. 5

   Check that the API endpoint is not overridden

   If you have set NUXARI_API_URL in the agent configuration, verify it points to the correct API endpoint. An incorrect override will cause all connection attempts to fail.

Registration token expired

Symptom:The agent fails to register and logs show "token expired" or "invalid token" during startup.

1. 1

   Confirm the token was generated recently

   In Settings > Edge Agents, check the creation timestamp of the pending agent entry. If it is older than 24 hours, the token has expired.

2. 2

   Delete the old pending entry

   Delete the expired agent entry from the list so the name can be reused cleanly.

3. 3

   Generate a new token

   Click Register Agent, give the agent the same name, and click Generate Token. Copy the new token immediately.

4. 4

   Deploy the new token promptly

   Update the agent configuration on the target host with the new token and start the agent within the 24-hour window. Do not generate the token far in advance of deployment.

Agent does not contribute to Coverage Map

Symptom: The agent is Active and heartbeating, but no coverage data from the agent appears in the Coverage Map, and no new evidence files are attached to relevant controls.

1. 1

   Verify a control pack is assigned to this agent

   In Settings > Edge Agents, open the agent detail view. Confirm that at least one control pack (such as the Linux Posture Pack) is assigned to this agent. Without an assigned pack, the agent has no instructions for what to collect.

2. 2

   Check that the control pack evaluation has run

   Go to Control Packs and locate the pack assigned to this agent. Confirm the last-run timestamp is recent. If the pack has never run, trigger a manual evaluation run from the Control Packs page.

3. 3

   Review agent-side collection logs

   In the agent log file, search for 'collection started' and 'collection completed' messages. If collection errors appear, they will identify which check failed and why (e.g., permission denied on a required path).

4. 4

   Confirm the agent user has the required OS permissions

   The agent process must run with permissions to read the data required by the assigned control pack. For the Linux Posture Pack, the agent user typically needs read access to /etc/passwd, /etc/sudoers, and systemd service state.

5. 5

   Wait for the next evaluation cycle or trigger a manual run

   Coverage Map data refreshes after each evaluation run. If a run just completed, allow up to 5 minutes for the Coverage Map to reflect the new evidence.

Agent running in air-gapped or isolated environment

Symptom: The environment has no direct internet access. The agent cannot connect to api.nuxari.io and the standard network path is unavailable by design.

1. 1

   Identify the closest network hop with internet access

   In many air-gapped environments, there is a DMZ or jump network that has outbound internet access. Deploy the agent on a host in that segment rather than in the fully isolated core.

2. 2

   Configure a forward proxy if needed

   If the agent host can only reach the internet through a proxy server, set HTTPS_PROXY in the agent's environment. The proxy must allow outbound HTTPS to api.nuxari.io.

3. 3

   Verify the agent binary can be transferred to the environment

   If the environment has no package management access, download the agent binary on an internet-connected machine, verify its SHA256 checksum against the published value on the Nuxari downloads page, then transfer it using your approved transport method.

4. 4

   Contact Nuxari support for fully isolated deployments

   If no outbound internet access is possible from any reachable network segment, contact Nuxari support. Offline collection export is available under certain support tiers for environments where no outbound path can be established.

Agent jobs stuck in queue

Symptom:Control pack evaluations or scheduled tasks assigned to this agent remain in a "queued" or "pending" state and do not start, even though the agent appears Active.

1. 1

   Confirm the agent is actually heartbeating, not just listed as Active

   In Settings > Edge Agents, check the exact last-seen timestamp. If it is more than 5 minutes old, the agent may have lost its connection since the last status refresh. Refresh the page and recheck.

2. 2

   Restart the agent process

   A clean restart clears any transient queue polling errors. Restart the agent and watch the logs for 'job received' messages to confirm it is picking up queued tasks.

3. 3

   Check agent resource usage

   If the agent host is under heavy CPU or memory pressure, the agent's job polling loop may slow significantly. Check host resource usage with top or htop and free up capacity if needed.

4. 4

   Verify the job queue is not paused

   In Settings > Scheduled Jobs, check whether the job queue is paused globally or for this specific agent. An admin may have paused the queue during maintenance.

5. 5

   Cancel and re-queue the stuck job

   If a specific job has been stuck for more than 30 minutes, cancel it from the Scheduled Jobs page and trigger a fresh manual run. This releases any lock the stuck job holds.