# Troubleshooting Most connector errors say what to do. Look up the message you see below. For `401` and other errors any call can get, see [API errors](https://getstream.io/agents/docs/api/errors/). The `getstream agents` commands below are in the beta CLI: ```sh curl -fsSL https://getstream.io/cli/beta/install.sh | bash ``` ## A user cannot connect | What you see | Why | What to do | | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------- | | `403` `server_side_only` on `POST /v1/agents/connections` or a sign-in | The call carries a user's token | Make the call from your server, with a server token | | `400` `owner.user_id must be the user this backend acts for, named by X-Stream-User-Id` | `owner.user_id` and `X-Stream-User-Id` name different users | Name the same user in both | | `404` `connection_not_found` when you read a user's connection | The call has no `X-Stream-User-Id`, or it names another user | Send `X-Stream-User-Id` with the user who owns the connection | | `400` `this consent is unknown, expired or already finished: start it again` on the handoff | The handoff token was used already. It works once | Start a new sign-in, and hand its token to the popup | ## Saving credentials fails | What you see | Why | What to do | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `409` `the connection's credentials changed since expected_revision: read it again and retry` | `expected_revision` is not the connection's `revision` | Read the connection with `GET /v1/agents/connections/{id}`, then send its `revision` | | `"code": "connector_credential_rejected"`, or `getstream agents connections tools` prints `Needs reconnect` or `The provider rejected the stored token or key`, and `validate` answers `"status": "needs_reauthorization"` | The provider no longer takes the connection's token, key or sign-in. The API does not check a token when you save it | `getstream agents connections tools ` says which. No `getstream agents connections` command saves new credentials: in the Dashboard, open the connection under **Library > Connectors** and choose **Replace token**, **Replace API key** or, for a sign-in, **Reconnect**, then **Validate**. With the API, save a working token with `PUT /v1/agents/connections/{id}/credentials` | ## A sync fails or leaves a connector out | What you see | Why | What to do | | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `connector github left out: the app has no connection with id or label "company"; add it and sync again` | No connection of the app has that label or id. With `required: true`, the whole sync fails instead | Run `getstream agents connections create github --label company`, then `getstream agents sync` again (see [App connection](https://getstream.io/agents/docs/connectors/shared-account/#with-the-cli)). In the Dashboard, the agent's **Tools** tab tags the connector **Not connected** and names the label to create. With the API, create the connection, then sync again | | `connector "github": no app connection with id or label "company": add the connection, or drop required` | The connector has `required: true`, and no app connection has that id or label | Create the connection with that label, or remove `required` | | `the sandbox may reach an allow list of domains, ranges or connectors' hosts, and the "not-verified" tier allows sandboxes no network: ...` | The agent's connector entry sets `sandbox: true`, and the organization is on the "not-verified" tier, which allows sandboxes no network. The same check runs on every save that changes the sandbox | Leave `sandbox: true` off the entry, and sync again. The sync works, and `getstream agents tools` shows `SANDBOX no`. See [Sandbox](https://getstream.io/agents/docs/connectors/sandbox/) | | `409` `agent config "support" (...) already answers its messages: one agent answers a channel connection` | Another agent already uses that Slack connection | Remove the entry from the other agent, or give this agent another connection | ## A conversation has no tools from a connector | What you see | Why | What to do | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `linear connect per person; a terminal test leaves them out` | A test in the terminal has no signed-in user, so it has no user's account to use | Test with `getstream agents test assistant --dashboard`. See [User connection](https://getstream.io/agents/docs/connectors/each-user-account/) | | The session's events include `connector_unavailable` with `"reason": "no_selection"` | The user has no connected connection to that connector, or has more than one | No CLI command shows it. In the Dashboard, the conversation shows a notice, such as "GitHub is not connected for you yet; the agent asks when it needs it". With the API, read the events on the WebSocket `GET /v1/agents/sessions/{id}/events`. Let the user [connect](https://getstream.io/agents/docs/connectors/each-user-account/#connect-from-your-app-with-the-api). With more than one, delete the ones the user does not need | | `required connector "github" cannot be used: not_connected: the connection is not connected` | The connector has `required: true`, and its connection is not connected yet | Save the connection's credentials, or remove `required` | | A tool fails with the server's own error, such as `web_search_exa error (401): Invalid API key`. `getstream agents test` prints `Tool exa__web_search_exa failed:` and the error | The MCP server refuses the key you saved. A server can list its tools without checking the key, so the connection can still show `Connected` | No `getstream agents connections` command replaces a saved key. In the Dashboard, open the connection: under **Tool calls**, the call's **Result** is **Provider failed**, and the call shows the server's error. Choose **Replace API key**. With the API, save the right key with `PUT /v1/agents/connections/{id}/credentials` | ## Deleting fails | What you see | Why | What to do | | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `409` `custom_search is used by connections ... and by agent config bindings ...: delete or unbind them first...` | You delete a connector that a connection or an agent still uses | Delete those connections and remove the entries, then delete the connector | | `409` `an agent config binds this connection as its fixed connection: unbind it first...` | You delete a connection that an agent uses with `connection` | `getstream agents tools ` shows the connection under ACCOUNT. Remove the entry from `agent.yaml`, run `getstream agents sync`, then `getstream agents connections delete `. To remove the last entry, keep `connectors: []`: a file with no `connectors` key leaves the agent's connectors as they are. In the Dashboard, the connection's **Used by** row names the agent. With `--force`, the delete goes ahead and leaves the entry naming a connection that no longer exists | ## Going further - [User connection](https://getstream.io/agents/docs/connectors/each-user-account/): Let each user connect their own account, from the dashboard or your own app. - [App connection](https://getstream.io/agents/docs/connectors/shared-account/): One account the app owns, for every conversation. - [Custom MCP servers](https://getstream.io/agents/docs/connectors/mcp/): Any MCP server: a public one, or one behind a key. - [Tools](https://getstream.io/agents/docs/connectors/choosing-tools/): See a connection's tools and offer only the ones the agent needs. --- For the most recent version of this documentation, visit [https://getstream.io/agents/docs/connectors/troubleshooting/](https://getstream.io/agents/docs/connectors/troubleshooting/).