# 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/). ## 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 backend, 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` | | `validate` answers `"status": "needs_reauthorization"` and `"code": "connector_credential_rejected"` | The provider refuses the saved token. A token is not checked when you save it | 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 | [Create the connection](https://getstream.io/agents/docs/ios/connectors/shared-account/#create-it-from-your-backend), 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` | | `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 [Each user's account](https://getstream.io/agents/docs/ios/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. Open the WebSocket `GET /v1/agents/sessions/{id}/events` to read the events | Let the user [connect](https://getstream.io/agents/docs/ios/connectors/each-user-account/#connect-from-your-app). 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` | The MCP server refuses the key you saved | Save the right key on the same connection | ## 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` | Remove the entry from `agent.yaml` and sync, then delete the connection | ## Going further - [Each user's account](https://getstream.io/agents/docs/ios/connectors/each-user-account/): Let each user sign in, from the dashboard or your own app. - [Shared account](https://getstream.io/agents/docs/ios/connectors/shared-account/): One account the app owns, for every conversation. - [Custom connectors](https://getstream.io/agents/docs/ios/connectors/mcp/): Any MCP server: public, behind a key, or with a sign-in. - [Choosing tools](https://getstream.io/agents/docs/ios/connectors/choosing-tools/): Offer only the tools the agent needs. --- For the most recent version of this documentation, visit [https://getstream.io/agents/docs/ios/connectors/troubleshooting/](https://getstream.io/agents/docs/ios/connectors/troubleshooting/).