Troubleshooting

Headings are 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 is the rest, after the two you will meet first.

The two you will meet first

authorization_required means this user is not connected. It never means "no data on this user", and it is not answered by retrying. Check the profile, and if it is not linked, mint the card:

const read = await profile.read({ sections: ["identity"] });
if (!read.profile.linked) {
  const connect = await profile.connect();   // the only thing that mints a link
  return renderCard(connect);                // renderCard is yours: it puts the result on the page; or put connect.connect_url in the reply
}

A user you are sure connected can still return 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 is not the fix for this one, and neither is 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 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 one 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 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 8, a per-user session lists 16. 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.