# Fix an Agent Step That Fails (https://www.shipfox.io/docs/how-to/run-and-troubleshoot/agent-provider-failures)

Description: 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 [#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 [#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](https://www.shipfox.io/docs/reference/model-providers)
to find a compatible harness. Use [Agent
integration fields](https://www.shipfox.io/docs/reference/workflow-schema#agent-integration-fields) for
tool selection rules.

## Follow the agent configuration warning [#follow-the-agent-configuration-warning]

Open the failed agent step. Shipfox shows a warning for known setup errors.

| Warning                        | Repair                                                                        |
| ------------------------------ | ----------------------------------------------------------------------------- |
| Configure credentials          | Open **Settings → Agents**. Configure the selected provider and test the key. |
| Update credentials             | Replace the saved key. Make sure **Test & save** succeeds.                    |
| Choose a supported provider    | Change the provider or harness to a compatible pair.                          |
| Choose an available model      | Choose a model from that provider or use its default.                         |
| Fix this step's agent settings | Check the prompt and any explicitly set provider, model, and thinking fields. |

Re-run the workflow after the fix. Change only fields named in the warning.

## Check tool and repository scope [#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:

1. The integration connection is enabled and belongs to the workspace.
2. The operation is included with the needed read or write choice.
3. The repository is installed and is inside the `repos` scope.
4. The external account still grants the operation.

Use [read-only integration tools](https://www.shipfox.io/docs/how-to/author-workflows/use-integration-tools)
or [write-capable integration tools](https://www.shipfox.io/docs/how-to/author-workflows/post-pull-request-review)
to rebuild the smallest valid selection.

## Check a shared session failure [#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](https://www.shipfox.io/docs/reference/limits#agent-sessions) and the runner logs.                                                                                      |

[Agent session fields](https://www.shipfox.io/docs/reference/workflow-schema#agent-session-fields) lists
the exact rules behind each reason.

## Check provider invocation failures [#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](https://www.shipfox.io/docs/how-to/run-and-troubleshoot/inspect-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 [#verify-the-repair]

Re-run the same workflow and open the new attempt.

1. Check the resolved harness, provider, and model.
2. Check that tool calls stay in the intended integration connection and repository.
3. 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](https://www.shipfox.io/docs/how-to/run-and-troubleshoot/inspect-runs-and-attempts) to select the right
attempt.