Troubleshooting

A blog path location fails its setup check

The three most common Check setup errors and their causes:

• no_response or http_error — the path does not reach vibecms. Save and deploy the route or rewrite, then check that it matches /blog and everything under it.
• redirects — the rule redirects instead of proxying. Rewrites must serve the response in place.
• not_proxied or old_proxy_link — your own site answered the health path, or the proxy uses a stale link. Copy the current snippet from Settings > Domain.

See Your blog at example.com/blog for every check code.

Agent sign-in fails

• If the sign-in link expired, start the connection again from the app.
• Sign in as the owner of the blog you want to connect. If you do not have a blog yet, create one in the dashboard first.
• If you see a localhost return warning, continue only when you started the connection from an app on this computer.
• If you disconnected the app, reconnect and approve it again. Disconnect takes effect immediately.
• A blog can have up to 10 active agent keys and connections combined. Disconnect an unused app or revoke an unused key under Dashboard > Connect before adding another.

See Connect an agent for setup and access levels.

The client lists tools but cannot read the site

Tool discovery requires authentication, but listing tools does not prove that the credential can read your site. Call sites.get. For a signed-in connection, check that the right blog was approved and the connection has not been disconnected. For a key, confirm the bearer header is attached to every MCP request, including discovery. The credential needs sites:read.

A write returns FORBIDDEN

The token is valid but lacks the operation’s required scope. Explain the missing capability. Do not widen the token automatically.

Publishing returns CONFLICT

The draft tip changed after approval or after the version was read. Fetch the post and latest version, preview the current content, then request fresh approval.

Image upload or publication is blocked

Check:

• Supported image type and 10 MB decoded-size limit
• Useful alt text for featured and inline images
• Hosted subscription and storage entitlement
• Whether the asset belongs to the current site

A public URL is missing

Use only the URL returned by vibecms. A null URL may indicate that the public origin or domain is not ready. Do not construct one from the slug.

Deployment readiness

• API liveness: GET /api/health/live
• API readiness: GET /api/health/ready
• Public health: GET /__vc-health

Hosted production deployment must use pnpm deploy:prod, which runs the project preflight, backup metadata capture, migrations, Worker deploys, and smoke checks in order.