Troubleshoot agents and the API

​

Authentication

​

Permissions and authorization

• TOOL_CALL_FORBIDDEN with retryable: false — the key or member lacks the underlying grant. Add the grant on the key (or use an OAuth session with permission); retrying the identical call won’t help.
• members list works but set-owner/set-access fails — discovery needs workspace_members:read; collaboration writes need customer_access:manage. They are separate grants and the full flow needs both.
• A key can’t see what its creator sees — API keys are independent principals and do not inherit the creator’s permissions or customer access.
• Writes reject a name — mutations take a customer ID, domain or exact name, and refuse a name that matches several customers (customers set-owner acme.com --member user_…). Resolve the ID with customers get first, and the member with ws-users list.
• set-owner or an archive prints a preview and exits 1 — nothing was changed. Outside a terminal these commands need --yes to confirm.

​

Empty or partial results

​

CLI output and scripting

• Expected JSON but got a table — pass --json explicitly, or ensure one auto-trigger: piped stdout, CI/GITHUB_ACTIONS set, or TERM=dumb.
• outlit in a cron/CI job exits non-zero — JSON errors go to stderr as {"error": …, "code": …}; all failures exit 1. See the error-code table.
• doctor reports a missing skill — run outlit setup <agent> (e.g. openclaw, claude-code, codex, gemini, droid, opencode, pi, skills).

​

MCP setup

• Wrong URL shape — it is workspace-scoped: https://mcp.outlit.ai/w/<workspace-slug>/mcp?toolsets=core,work,meta, copied from Settings → CLI & MCP. Loads core, work and meta. Add admin or identity, or use ?toolsets=all for every tool. Without ?toolsets the URL loads every tool. A bare mcp.outlit.ai URL with no workspace is not valid.
• An admin or identity tool is missing — the slim URL leaves those toolsets out. Add them (?toolsets=core,work,meta,admin) or use ?toolsets=all; outlit_list_toolsets names the URL that adds one.
• Tools visible but calls forbidden — OAuth runs as the signed-in member; API-key calls use the key’s grants. The catalog is identical either way; authorization is not.
• This is not the docs search MCP — the docs site hosts a separate search-only MCP endpoint. It has no customer tools; use the workspace URL above for product data.

​

Tracking and ingest

​

Identity mismatches

• Duplicate customers appearing — check outlit merge-suggestions list; reject wrong pairs with merge-suggestions reject <id>, merge real duplicates with customers merge (preview first).
• User events attributed to the wrong account — Outlit Browser SDK and Outlit server SDK identify() accept customerId for explicit account attribution; Outlit server SDK track() does too.
• Personal-email domains — user@gmail.com resolves to an individual customer keyed on the full address, not a gmail.com company; expect separate customers per personal email.