Connect your AI
Troubleshoot a connection
Find the failed stage without exposing credentials or weakening the governed path.
Diagnose the connection in order. Do not respond to a failure by widening scopes, changing tenants, exposing internal ports, or bypassing the Twin query route.
| Symptom | Likely boundary | Safe next check |
|---|---|---|
| Cannot add the connection | Provider workspace policy | Ask the ChatGPT or Claude owner to add the custom app or connector |
| OAuth callback rejected | Client registration | Compare the callback URL character-for-character with the registered redirect URI |
401 Unauthorized | Token, issuer, audience, or active user | Re-authenticate through the protected sign-in flow; do not paste the token into chat |
403 Forbidden | Scope or organisation mapping | Check the exact scope for the action: twin.connections, twin.onboarding, twin.query, twin.read, or twin.write, plus the organisation mapping |
| Channel not found | Channel access, organisation mapping, or an unknown reference | Run twin channels --json and use the exact returned ID or slug; do not broaden the credential |
| Deterministic field rejected | Channel schema | Inspect the channel again and use an active returned field key; never substitute raw SQL |
| Query stays queued or running | Twin runtime | Keep the query ID and request ID; ask support to trace the routed session |
| Query fails during routing or composition | Twin router or governed data contract | Keep the query, task, and session IDs; inspect the exact run rather than broadening capabilities or querying source tables |
| Channel, view, session, or artifact read fails with a gateway error | Public gateway or tenant service | Keep the structured diagnosticId returned by the API or CLI so support can correlate the safe gateway request log |
MCP server is missing twin_channels_* or twin_query* tools | Wrong server or outdated configuration | Disable it and compare the URL with the Twin connection details |
| Hosted Claude cannot reach the server | Public network or TLS | Confirm the configured gateway is public HTTPS, not localhost, VPN-only, or Tailscale-only |
twin login does not open or finish | Browser callback or local credential store | Retry from the same computer, keep the terminal running, and complete the browser sign-in; do not paste the callback token |
| CLI is using the wrong organisation | Saved CLI organisation context | Run twin status --json and twin organisations --json, then switch with twin organisations --use <id-or-exact-name>; do not log in again or guess an organisation |
twin channels is forbidden | Organisation mapping, scope, or tenant route | Ask MLX to verify twin.read, the central organisation mapping, and the registered HTTPS tenant route |
--allow-write is present but a channel write is forbidden | Existing OAuth grant lacks twin.write | Run twin login again and approve the updated scope; do not paste or broaden credentials manually |
Record creation returns 422 Source-backed object type | The selected object type projects an external source | Create the row in the source system; do not copy it into a native channel |
View update returns 409 Conflict | The saved view changed after it was inspected | Re-read the view and show the user the competing definition before preparing a new update |
Channel View Has No Dashboard Data | --data was used with a table, board, form, or other non-dashboard view | Inspect the view, then use a deterministic records query or read a dashboard view instead |
| Deterministic request is invalid | A field, operator, or metric function does not match the typed contract | Read the validation path, such as metrics[0].function, and compare the intent with twin help --json |
| Codex or Claude Code MCP cannot authenticate | Optional MCP credential configuration | Confirm the configured credential reference without printing its value, then restart the client |
Capture safe support details
Include:
- provider and client type;
- time and timezone;
- gateway hostname, without query strings or credentials;
- connection name;
- channel ID and object type ID when relevant;
- HTTP status or safe error code;
- gateway request ID or structured
diagnosticId; - query ID, task ID, or session ID when returned; and
- the stage that failed.
Do not include tokens, secrets, cookies, raw authorization headers, full request bodies, or private source data.
Remove a local connection
Run twin logout to remove the saved CLI credential. If you also added optional
MCP configuration, remove only the twin entry and restart the client. Preserve
every unrelated server and setting. Removing local configuration does not revoke
the OAuth client; ask a Twin administrator for revocation when that is intended.