Skip to main content

Troubleshoot a background agent

Open Build > Background Agents and select the affected agent. Start with the symptom below. For infrastructure failures on your own runtime, use that runtime's setup or deployment guide.

A platform is missing​

Check Agent Types in organization settings. Enable the runtime and supply its required configuration. The creation form lists enabled runtimes, not every platform value accepted by the API.

Deployment fails​

Read the deployment error under Settings > Deployment & Sync. Check the runtime's configuration and credentials, then deploy again. For platform-specific errors, use the setup guide linked from Platforms.

On a registered platform using pull delivery, Waiting for platform means Willow is waiting for the runtime to collect and acknowledge work. Ask the runtime operator to check collection and connectivity; see Use the harness in your cluster.

The agent is Active and Synced but tools fail​

  1. Open Tools and check the affected MCP server's authentication control.
  2. If it reads Auth not set, choose and save the integration identity.
  3. On a per-user server, replace Use the MCP server default with an initiator or connected account. The default does not supply an agent identity on these servers.
  4. Check that the required individual tool is enabled.
  5. Inspect the failed call in Monitor > Logs. Authentication, policy, arguments, and upstream errors require different fixes.
  6. Deploy saved changes where applicable and repeat the affected test.

An external client stops authenticating​

Check whether the client's token was recreated or revoked, or the agent was disabled. A recreated token's previous secret becomes invalid. Deploying replaces only the platform token, so use a manual token for an external client to keep it working across deploys. Copy the exact endpoint from Connect; gateway path prefixes are part of that URL. See Agent credentials.

A Slack agent stays silent​

Check that the dedicated Slack app is connected under Settings > Slack App. In Triggers > Channels, check the channel's response mode and the direct-message default. Confirm that the app is present in the intended channel. See Slack setup troubleshooting.

The agent returns an answer without the expected tool call​

Inspect the session events. If no relevant tool was called, check that the tool is assigned and enabled, then make the test request explicit about using it. Compare the actual tool output with the answer. A plausible answer alone does not verify the connection.

For upstream tool errors, test the MCP tool to isolate the server connection from the agent's behavior.

No sessions are listed​

A newly configured agent has no run history. Confirm that a test or matching trigger actually started a conversation. Check the result at the runtime and its supported session interface; the dashboard and API entry points have platform-specific behavior.

On this page