Fix an Agent Step That Fails
Find why an agent step fails. Repair its provider, model, tools, or access.
Use this guide when an agent step fails. Start with the error shown in the run. Sync, setup, and provider errors need different fixes.
Before you begin
You need the failed run and access to workspace agent settings. A tool failure may also require integration settings.
Check whether the workflow synced
If the workflow does not sync, open its sync error.
- A harness and provider mismatch requires a compatible pair.
- An unknown native tool requires a name supported by the selected harness.
- An integration selection requires a valid integration connection and a supported integration tool token.
- A write-capable integration selection also requires
allow_write: true.
Fix the YAML and wait for it to sync. Use Model Providers to find a compatible harness. Use Agent integration fields for tool selection rules.
Follow the agent configuration warning
Open the failed agent step. Shipfox shows a warning for known setup errors.
| Warning | Repair | Then |
|---|---|---|
| Connect a provider | Open Settings → Agents. Configure the selected provider and test the key. | Rerun the job. |
| Update your credentials | Replace the saved key. Make sure Test & save succeeds. | Rerun the job. |
| Choose another model provider | Change the provider or harness to a compatible pair. | Start a new run. |
| Choose another model | Choose a model from that provider or use its default. | Start a new run. |
| Model is not available in this workspace | Follow the action in the warning, or choose another model. | Rerun the job. Start a new run if you change the model. |
| Complete the agent step | Check the prompt and any explicitly set provider, model, and thinking fields. | Start a new run. |
A rerun keeps the workflow file of the original run. After you change the workflow file, start a new run. Change only fields named in the warning.
Check tool and repository scope
If the agent starts but a tool call fails, open the tool result in the step log.
For a native tool, check that the harness exposes it. For an integration tool, check all these facts:
- The integration connection is enabled and belongs to the workspace.
- The operation is included with the needed read or write choice.
- The repository is installed and is inside the
reposscope. - The external account still grants the operation.
Use Agent integration fields to rebuild the smallest valid selection. For GitHub, see the read-only and write examples.
Check a shared session failure
If a step that names a session fails before the agent starts, open its error
reason.
| Reason | Repair |
|---|---|
agent_session_key_invalid | Start the key with a letter or digit. Use only letters, digits, dots, underscores, or hyphens, up to 128 characters. Check the expression inside the key. |
agent_session_held | Another attempt is resuming the same key right now. Add a needs edge between the jobs, set mode: fork on one step, or use separate keys. If no other step is running, an earlier attempt has not released the key yet. Wait for Shipfox to clean it up, then re-run failed jobs. |
agent_session_harness_mismatch | Remove harness from the step, or set it to the harness that created the session. |
agent_session_unavailable | The transcript could not be stored or loaded, or one segment passed the size cap. Re-run failed jobs once. If it repeats, check Limits and the runner logs. |
Agent session fields lists the exact rules behind each reason.
Check an MCP server failure
A step with mcp_servers fails with agent_mcp_server_unavailable in these
cases:
- A server did not start, or it did not answer at its
url. - A server did not list a tool from
include. - A server listed a tool that the agent cannot use.
The agent cannot use a tool in these cases:
- The full tool name has more than 64 characters.
- The name has characters other than letters, numbers, underscores, and hyphens.
- The name is the same as another tool on the step.
The error message names the server. When a server did not start, the message also shows the last part of its error output. See Use your own MCP server.
Check provider invocation failures
An invocation failure means the setup resolved but the provider call failed. Read the last agent message and error in step logs.
- Authentication rejection: test and replace the provider key. A saved key may be revoked or lack account access.
- Rate limit: wait for the provider's retry window, then re-run the workflow. Reduce concurrent agent work if the limit repeats.
- Unavailable model: choose another model or use the provider default.
- Network or provider server error: check the provider status and the runner's outbound access. Re-run once after the service recovers.
- Custom endpoint failure: use Edit and Test & save. Check the URL, protocol, headers, and model list.
Do not keep re-running a request that is invalid. Fix its setup first.
Verify the repair
Rerun the job after a settings fix. Start a new run after a workflow file change. Open the new attempt.
- Check the resolved harness, provider, and model.
- Check that tool calls stay in the intended integration connection and repository.
- Check that the step returns a response and succeeds.
If the new attempt has an unknown error, save the run, job, step, and attempt IDs. Include the last message and runner logs in the handoff. Use Inspect a run to select the right attempt.