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.
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, 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 |
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. 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 |