Troubleshooting

Each bold label below is the exact text you will see in a stack trace, a tool result, or a JSON-RPC error. The five failures every integration meets are in the Quickstart. This page starts with the two you will meet first, then covers the rest.

The two you will meet first

authorization_required means this user is not connected. It never means "no data on this user". Retrying does not fix it. Check the profile. If it is not linked, send the user to Configure:

const read = await profile.read({ sections: ["identity"] });
if (!read.profile.linked) {
  const connect = await profile.connect({ returnUrl: RETURN_URL });   // the only thing that mints a link
  return res.redirect(connect.connect_url);   // Quickstart step 3; in a chat reply, show connect.connect_url instead
}

A user who did connect can still get this from a second agent of yours. Linking a real account clears every agent's approval except the one they approved, so each agent asks once. The same connect() fixes it. See Variations.

commit_required (-32009) means a read in this turn left an obligation the turn has not cleared. Commit the turn, then retry the call:

await profile.commit({ messages: turnMessages });   // the turn so far
const retry = await profile.read({ sections: ["identity", "preferences", "summary"] });

configure_connect does not fix this, and neither does a new session.

Sign-in

redirect_uri must exactly match client registration. Register the full callback with npx configure add origin https://yourapp.com/callback. Scheme, host, port, and path must match byte for byte.

Unknown OAuth client. or Invalid client credentials. The client id or secret in your environment is stale or belongs to another account. Run npx configure setup --force and redeploy.

PKCE verification failed. / Authorization code was already used. Keep the verifier for the whole round trip, and exchange each code once. A page that mounts twice exchanges twice. personalize() and the scaffolded callback already guard against this.

Access denied: provide an agent user token or X-User-Id (-32001) over MCP, and 401 with code token_missing and Provide Authorization Bearer token or X-User-Id header. over REST. No user was resolved on a per-user call. Send the user's token or your X-User-Id. configure_connect is the only tool that works without either.

Tools

Tool configure_gmail_search is not enabled for this profile runtime Include the connector in profile.tools({ connectors: [...] }) before dispatching. The narrowing sticks to that handle. A later, wider tools() call does not widen it back, so make one handle per scope.

Notion not connected. Ask user to connect Notion first. (-32000, and the same shape for every app) The user has not connected that app. A read carries data.connect_url. A state-changing tool carries data.suggested_action.url instead. Show whichever one is there. Never build one. The literal string tool_not_connected is the error's category, not text you will see.

permission_needed (-32000) The connected account lacks a scope. Use data.suggested_action.url from the payload.

Tools do not appear in the MCP client. The list depends on the credential. An API key alone lists 9. A per-user session lists 17. Most clients cache the list at connect time, so reconnect after minting a session.

-32601 on prompts/list Expected. Configure serves no prompts. resources/list does answer. It carries the connect card's UI resource, which is how the card reaches a host.

Commits

commit_required (-32009) A read left an obligation this turn did not clear. Commit the turn, then retry.

profile.commit requires bounded source material / at most 20 messages / 16000 characters Send the turn, not the archive. Long transcripts go through import, not commit.

forget() resolved but nothing was deleted. Check deleted in the response. An agent deletes only what it saved itself.

CLI

Not signed in. Run npx configure login first The CLI wants a developer login, not an API key.

No OAuth client yet. Run: configure setup --users Sign-in commands need the client the wizard creates.

npx configure verify rejects CONFIGURE_API_KEY The key was revoked or belongs to another account. Re-run setup.