Troubleshoot MCP, CLI, and API integrations
Resolve authentication, site targeting, permission, upload, compile, and publication problems in a practical order.
When a developer tool fails, identify the operation and its error before reconnecting everything. Authentication, target selection, site permissions, plan access, and publication are separate checks.
The session expired or returns 401
A 401 UNAUTHORIZED response means the management API did not accept the authentication token. In the CLI, sign in again:
neopress login
neopress whoami
neopress --site 123 sites getReplace 123 with your site ID. If NEOPRESS_ACCESS_TOKEN is set, that token overrides the saved CLI session. Update or remove the override in your environment before relying on a fresh login. whoami reports the stored CLI session; it is not a complete check of an externally supplied token.
For remote MCP, reopen the connection's authentication flow in the AI tool. Confirm which account is signing in. Adding custom OAuth scopes or pasting a different kind of key will not repair an expired session.
The wrong site is selected
neopress --site 123 sites current
neopress --site 123 sites getThe first command shows the resolved target; the second verifies server access. Without an explicit flag, an environment variable, project configuration, or saved global site may select a different site. In MCP, ask the assistant to list sites and select the correct numeric ID, then read it back. A page or entry ID must belong to that same site.
The request returns 403
FORBIDDEN: check site membership and any role requirement for the operation. Site publication through the developer tools requires an owner or admin.INSUFFICIENT_SCOPE: check the account's assigned work permissions in team settings. Being allowed to edit content does not automatically allow page editing or publication.PLAN_REQUIRED: verify the target site's current entitlement. Developer access starts at Launch, while additional languages and saved events or funnels require Growth.
If all of your sites lack active developer access, listing or creating sites through the API can also be blocked. Reconnecting the same account does not change its plan or permissions.
An upload or compile fails
Remote MCP cannot read a local path such as ./photo.png. Ask the assistant to import a publicly reachable file URL or use the temporary upload URL workflow. Local stdio MCP can upload local files. Registering an external asset URL alone does not copy that file into Neopress storage.
For 422 COMPILE_ERROR, read the compiler message and current runtime contract. Check imports, component syntax, collection query labels, and managed form bindings. Compile the changed page again before publishing.
The request is busy, limited, or interrupted
A 409 ONBOARDING_GENERATION_IN_PROGRESS response means initial site generation is still running; wait for it to finish before writing. A 429 RATE_LIMITED response calls for fewer concurrent requests and a longer retry interval. Limits differ by operation and may be shared by related calls.
After a timeout or connection error during a write, read the resource before repeating the request. The server may have completed it even though the response did not reach your tool.
The live page still looks unchanged
Check that you published to the production environment, not just saved or compiled a draft. Review pending changes with neopress --site 123 publish preview. Publish edited CMS entries separately, include changed layout or global styles in site publication, and verify the page's public languages. Then open the actual visitor URL.
If the issue remains, share the command or tool name, site ID, time, and error code with support. Remove access tokens and private content from the report.