# Errors and troubleshooting

> Every error people hit with the Stensul MCP server, why it happens and the fix.

Source: https://stensul.com/developers/troubleshooting/

## Check these first

1. **Is your instance name in every URL?** The MCP URL, the redirect URI and the OAuth URLs all need it: `https://mcp.stensul.com/<your-instance>/…`
2. **Does it fail for everyone, or one person?** Everyone on a connection means a **scope**. One person means a **permission**.
3. **Does it work in the Stensul app?** If yes and it fails in your AI host, it's the connection's scopes; the app doesn't use them.
4. **Did an admin just add a scope?** That revokes existing tokens. Sign in again.

## Error table

| Status | Message | Cause | Fix |
| --- | --- | --- | --- |
| 401 | Authentication expired or missing | The session's authorization expired. | Sign in again when the host prompts. On a 401 or 403, the server's instructions tell the model to re-check sign-in first. |
| 403 | Insufficient OAuth scope (403): The token lacks the required scope | The API connection doesn't have the scope this tool needs. | An admin adds the scope to the API connection. Then sign in again: adding a scope revokes existing tokens. |
| 403 | Invalid scope(s) provided. | The connection was created with only `api-read`/`api-write`, which apply to server-to-server integrations and do nothing for MCP. | Select the granular scopes (`emails:read`, `emails:write`, `libraries:read`, …) on the connection. |
| 403 | API error (403): Action is unauthorized. | The signed-in user's role lacks the permission, for example `edit_campaign`. | Grant the permission to the user's role in Admin > Users & Roles. It works for other users on the same connection. |
| 403 | API error (403): Sent emails cannot be edited. | The email has already been sent. | Nothing to fix. Copy it and edit the copy. |
| 403 | Access denied (403): Your IP address is not in the allowed list | The caller's IP isn't in the external API allowlist. | An admin adds the IP in Settings > External API > Allowed IPs. |
| 403 | API error (403): | The server didn't say which check failed. | Work through the other 403 rows: confirm sign-in with `stensul-check-auth`, then scopes on the connection, the person's permissions, and the IP allowlist. |
| 409 | Version conflict | The email changed since your last read, and you passed its old `save_version`. | Read the email again and re-apply your change on the current version. Never retry by dropping `save_version`. |
| 422 | Field not enabled for this library | `stensul-update-email-settings` sent a title, subject line or preheader the library doesn't enable, so the whole call is declined. | Send only fields the library enables (see `stensul-get-libraries`). |
| declined | Content declined by a guardrail | A value is outside what the template allows: an off-palette color, a size out of range, locked text. | Keep the value within the guardrail or make no change. Guardrails are enforced by Stensul and cannot be overridden from a chat. |
| sign-in | Redirect URI mismatch | The redirect URI on the API connection is missing your instance name or doesn't match exactly. | Set it to exactly `https://mcp.stensul.com/<your-instance>/oauth/callback` (Writer also needs its own callback). |
| 410 | Gone | A client is still calling the old shared `/mcp` endpoint with `X-Stensul-*` headers, which was removed. | Use the per-instance endpoint `https://mcp.stensul.com/<your-instance>/mcp` with OAuth. Existing Client IDs keep working. |
| 422 | Fixed header or footer can't be added | `stensul-add-email-module` was asked for a module the library fixes at the top or bottom of every email. | Nothing to fix. Those modules are governed by the library. Report it and don't offer a substitute. |
| 422 | The "before" module is not in this email | The email changed since it was read, so the module named in `beforeModuleId` is gone. | Read the email again and ask the user where the new module should go now. |

## Sign-in problems

| What you see | Fix |
| --- | --- |
| No API connections page in Stensul | The external API isn't enabled, or you don't have `access_admin_api_connections`. Ask your Stensul customer success manager. |
| The client secret isn't shown anymore | It's shown once. Create a new connection for a fresh ID and secret. |
| ChatGPT won't finish connecting | Clear the pre-filled **Authorization server base** and **Registration URL** fields. Keep Auth URL, Token URL and Resource. |
| Writer asks for a client secret | Expected: create the connection with PKCE off. |
| Claude or ChatGPT asks for a client secret | Leave it blank: PKCE connections have none. |
| Stensul isn't listed in Claude's Customize > Connectors | Your Claude admin hasn't added it yet. Ask them to add the custom connector under Admin settings > Connectors. |
| Image upload from the chat fails in Claude | Allow `<your-instance>.stensul.com` in Claude's **Capabilities > Additional allowed domains**. |
| Two browser tabs or `EADDRINUSE` in Claude Code | Pin `--callback-port 3334`. |
| A change doesn't show in the preview | Close and reopen the email, especially if it's also open in the Stensul editor. |

## Reporting a problem

Send your Stensul contact, or help@stensul.com: which host you used, what you asked, what you expected, what happened, and a screenshot. Don't include tokens or client secrets.