Troubleshooting

MCP

The client returns 401 or “authentication required”

• Confirm you copied the entire plr_mcp_v1_... key.
• Confirm the client sends Authorization: Bearer <key> on every request.
• Check whether the key expired or was revoked.
• Restart the client after changing its environment.
• Do not use a Pollaris web-login token, model-provider key, or public form slug.

The client cannot initialize

• Use Streamable HTTP, not stdio or legacy SSE.
• Use the complete URL ending in /mcp — production is https://mcp.pollaris.cc/mcp.
• For local Pollaris, ensure the client can reach http://localhost:8002/mcp from the environment where it runs.
• A remote client cannot reach localhost on your computer.

A workspace or form is missing

The key's workspace grant and your live membership are both enforced. Create a new key with the intended workspace, or ask a workspace owner to restore the required membership. Archived forms are omitted unless the client requests that status.

Reads work but generation or writes fail

• Generation needs pollaris.forms.generate and an editor/owner workspace role.
• Draft creation and saving need pollaris.forms.write and an editor/owner role.
• The Pollaris deployment must have its AI generation provider configured for generate_form_preview.

“Draft conflict”

Someone saved the form after the assistant loaded it. Reload with get_form_draft, reconcile both versions, and save using the new draft_revision and a new idempotency key.

Embeds

ORIGIN_NOT_ALLOWED

Add the exact parent-page origin in Share → Embed. Scheme, hostname, and port must match. Remove paths and trailing slashes. Do not test by opening an HTML file directly; serve it from localhost instead.

FORM_NOT_FOUND or a blank embed

Confirm the form is published and the slug is correct. Draft-only forms are not public. For one-page mode, also confirm the form's embed settings are enabled.

One-page submission is rejected

Confirm the form is linear and Enable atomic one-page submissions is on. A branched, backward, or scored form must use the step-by-step SDK.

VALIDATION_FAILED

Match every HTML field name to its stable Pollaris key. Convert numeric controls to numbers and multi-select values to arrays. Do not send unknown fields.

MANIFEST_STALE or session errors after publishing

Reload the form or manifest. The published schema changed after the page loaded. The standard SDK loads and supplies the manifest version automatically.

Browser CORS or CSP errors

• Add your site to the form's allowed origins.
• Allow the Pollaris API in your site's connect-src policy.
• For iframes, allow the hosted-form origin in frame-src.
• Allow the embed CDN in script-src.
• Never enable credentialed browser requests for the public embed API; the SDK deliberately uses credentials: 'omit'.