Troubleshoot Agent Behavior
Most problems with a deployed agent show up in one of three places: the agent’s Status on the Deployed Agents tab, a banner on the agent’s detail header, or the agent’s Logs tab. This page covers the problems you are most likely to encounter and how to fix them.
|
The Logs tab on the agent detail page is your primary diagnostic tool. It streams each cycle live and names the stage that failed. Open it first whenever an agent fails or behaves unexpectedly. See Monitor Agent Health. |
Agent Fails or Reports Issues
Symptom: the agent shows status Failed, or its detail header shows a red "This agent reported issues" banner with a failing log line such as ✗ Missing required environment variables.
Most common cause: the agent’s template references configuration values it was never given. A template that uses raw ${ENV_VAR} references, but does not declare matching template parameters, surfaces no fields in the deploy wizard, so nothing prompts you for those values. The agent deploys, then fails at runtime when the missing values are needed.
How to Fix It:
-
Declare the values as template parameters. In the Agent Builder, add a parameter for each value the agent needs (Agent Configuration → Parameters). Declared parameters appear as fields in the deploy wizard’s Set up your agent step, so the wizard prompts you to supply them at deploy time. Redeploy the agent.
-
Or supply the values at the network level. Register each value as a Network Tool or Resource of type Environment Variable on the network (turn on Treat as secret for credentials). The deploy wizard then offers the value as a default for matching environment-variable references. See Provide Tools for Agents in a Network.
After you supply the values, redeploy the agent and confirm it progresses to Running. See Deploy an Agent.
|
Open the Logs tab to read the exact failing line. It names which value or which stage failed, so you know exactly what to declare or supply. |
Agent Is Stuck in Pending
Symptom: the agent stays at status Pending and never moves to Deploying or Running.
Most common cause: the orchestrator you deployed the agent to is not running, so nothing picks the agent up.
How to fix it:
-
Open the agent’s Network and then its Orchestrator (both are linked from the agent’s Overview tab).
-
Check the orchestrator’s status. If it is
Staleor has never connected, the Docker container that runs it is not up. See Orchestrator Is Stale or Never Connects. -
After the orchestrator is connected and healthy, it picks up a
Pendingagent and progresses toRunningwithin seconds.
Orchestrator Is Stale or Never Connects
Symptom: an orchestrator shows Stale, or a newly added orchestrator never leaves "Waiting for first heartbeat…".
An orchestrator runs as a Docker container on your own host and checks in with the Control Plane. When those check-ins stop, or never start, the Control Plane marks it Stale, and the agents it runs can show stale, out-of-date status.
How to fix it:
-
Confirm the container is running. On the orchestrator host, check that the Docker enrollment command actually ran and the container is up. If it exited, restart it and check its container logs.
-
Check the enrollment token. The enrollment command carries a short-lived token. If too much time passed between when you generated the command and when you ran it, the token can expire. On the orchestrator (or in the deploy wizard’s Connect your orchestrator step), use Regenerate token to get a fresh command, then run it on the host. The orchestrator detail page also has Show enrollment instructions to re-display the command.
-
Wait for the first heartbeat. After the container starts, the wizard shows "Waiting for first heartbeat…" until the orchestrator connects. Next / Done stays disabled until it does. If it never connects, the host cannot reach the Control Plane. Check outbound network access from the host.
A stale orchestrator does not automatically mean its agents have failed. The agents can still run while the orchestrator is briefly unreachable. After it reconnects, the stale indicator clears on its own. See Deploy an Orchestrator.
Agent Runs but Does No Useful Work
Symptom: the agent shows Running but its Success Rate is low, or it is clearly not acting on data.
How to diagnose:
-
Open the Logs tab and watch a few cycles. The log line names the stage that failed, whether sense (a source is not publishing or a connection is unreachable), reason (a large language model (LLM) error, such as an expired key or wrong model ID), or actuate (a downstream call was rejected).
-
Open the Overview tab and check the Connections list for any connection that reports as failed. Its last error names the failure.
-
Open the Configuration tab to confirm the deployed agent has the topics, rules, and values you expected.
See Monitor Agent Health for the full diagnostic flow.
Cannot Delete a Network
Symptom: on a network’s Delete network dialog, the Delete button is disabled and the dialog warns that the network still has orchestrators.
Cause: a network cannot be deleted while it still has orchestrators attached. This guard prevents orphaning running agents.
How to fix it: reassign or remove the network’s orchestrators first, then delete the network. You confirm each orchestrator deletion separately, and you can delete an orchestrator even while it has agents. The Control Plane then stops managing those agents. See Create a Network.