Troubleshooting

Search this page for the error message from your stack trace, tool result, or JSON-RPC response. Bold labels preserve the exact error text. See the Quickstart for common integration errors.

Connection and commit errors

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 connected user can receive this response from another agent owned by your developer account. Account linking clears previous approvals and grants access only to the approved agent. Use connect() to request approval for each additional agent. See Variations.

commit_required (-32009) means a profile read requires a conversation commit for the current turn. 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. Tool restrictions remain attached to the profile handle. A later tools() call does not remove them. Create a separate handle for each 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 creating 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 profile read requires a conversation commit for the current turn. Commit the turn, then retry.

profile.commit requires bounded source material / at most 20 messages / 16000 characters Send the messages from the current turn to commit. Use import for long transcripts.

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.