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.
The getstream agents commands below are in the beta CLI:
curl -fsSL https://getstream.io/cli/beta/install.sh | bashA 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 <connection> 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). 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 |
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 |
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. 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 <agent> shows the connection under ACCOUNT. Remove the entry from agent.yaml, run getstream agents sync, then getstream agents connections delete <connection>. 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 |