ZenCreator MCP Docs
/
Connect
View as Markdown Open in ChatGPT Open in Claude

Troubleshooting#

Common problems and how to fix them. Each entry follows the same shape: symptom -> cause -> fix.

Errors from ZenCreator tools come back as tool results, not crashes — your client sees a short, actionable message telling it what to try next. The notes below explain what each one means and how to recover.

"Out of credits" (HTTP 402)#

Symptom. A generation tool fails and the result says you're out of ZenCreator credits, or a tool returns a structuredContent payload like:

{
  "error_code": "insufficient_credits",
  "out_of_credits": true,
  "purchase_url": "https://app.zencreator.pro/billing",
  "message": "You're out of ZenCreator credits. Top up at https://app.zencreator.pro/billing to keep generating."
}

Cause. Generation spends credits, and your balance reached zero. The backend returns HTTP 402 with the structured signal above.

Fix. Top up at https://app.zencreator.pro/billing, then retry the generation.

Avoid it next time. The same out_of_credits flag and purchase_url also appear in zencreator_get_me, so you can check your balance proactively before submitting work. And always price a job before you commit to it: call zencreator_estimate_price for one candidate, or zencreator_compare_prices to shop across a generation tool's models (cheapest first). See ./tools/account.md.

"Adult content is disabled" / NSFW request refused#

Symptom. An NSFW generation is rejected, or a model you asked for isn't allowed on your account.

Cause. Two account gates control uncensored generation:

  • nsfw_allowed — adult content must be enabled on the account.
  • is_trusted — required for models marked (trusted).

Both are reported by zencreator_get_me. If nsfw_allowed is false, the request is refused before any credits are spent.

Fix.

  • If nsfw_allowed is false: enable adult content in your ZenCreator account settings at https://app.zencreator.pro, then retry.
  • If the tool or model is (trusted) / 🔒 and you aren't trusted yet: Trusted Status is granted automatically after your first successful payment (buy any credit pack in Billing) and is permanent — make that first payment, or pick a non-trusted model for the same generation tool. Use zencreator_get_tool_schema to see which models a generation tool offers.

If your orchestrating client refuses to author explicit prompts, the optional zencreator_craft_prompt helper (present only on deployments with the prompt-agent sidecar) can write model-specific NSFW prompts for you — it spends no ZenCreator credits. See ./tools/generation.md.

Connector shows "disconnected" or returns 401#

Symptom. The ZenCreator connector reads as disconnected, tools stop appearing, or a call comes back with an authentication failure ("re-authorize with the ZenCreator MCP server").

Cause. Your access token expired and couldn't be refreshed, or the authorization was revoked. The MCP server is OAuth-only — every request needs a valid, audience-bound token.

Fix. Re-run the OAuth login. Tokens normally refresh automatically; you only need to do this when the grant was revoked or refresh failed.

  • Claude Code: start claude, run /mcp, pick zencreator, choose Authenticate, approve in the browser. Check state with claude mcp list (shows "Needs authentication" until you log in). See ./connect/claude-code.md.
  • Claude Desktop / Claude.ai (web): reconnect the custom connector in Settings -> Connectors and complete the browser login again. See ./connect/claude-ai.md.
  • Cursor: trigger the server again so it re-runs the browser OAuth login. See ./connect/cursor.md.
  • ChatGPT: reconnect the connector under Settings -> Connectors and complete the OAuth login. See ./connect/chatgpt.md.

There are no API keys to rotate — the whole flow happens in your browser.

Video generation times out#

Symptom. A video job (e.g. videogen, text_to_video, video2video, lipsync, video_upscaler) hangs or the request aborts before finishing.

Cause. Video takes far longer than images (typically ~60-180s). zencreator_run_and_wait blocks until the job reaches a terminal status — fine for images this turn, but too slow for video, so the call can time out.

Fix. Don't wait synchronously for video. Instead:

  1. Submit with zencreator_create_task — it returns a task id immediately.
  2. Poll zencreator_get_task until the call reaches a terminal status (space your polls — see the rate-limit note below).
  3. Fetch the result with zencreator_get_call_result to get the full output and the generated asset_ids (per-call output is lazy and is null while polling).

Reserve zencreator_run_and_wait for images. See ./tools/generation.md.

Rate limited (HTTP 429)#

Symptom. A tool result says the rate limit was exceeded and to back off.

Cause. Too many requests in a short window — most often tight polling loops on zencreator_get_task or zencreator_get_processing_tasks.

Fix. Back off and retry after a few seconds. Space out polling — wait at least 2 seconds between polls — and prefer zencreator_get_processing_tasks as a cheap "is anything still running?" check instead of hammering zencreator_get_task.

Images don't show up in the chat#

Symptom. A generation succeeds but no image appears in the conversation.

Cause. Some clients only render MCP images inside the tool-result panel, which can be collapsed by default — the image is there, just hidden.

Fix.

  • Expand the tool-result panel to view the inline image.
  • Or call zencreator_get_asset_preview_url with the inline option, which attaches the preview image as an image content block so it renders directly in chat. Inline previews are capped at 2 MB per image and 8 MB total per call; above that the tool falls back to returning a URL with a note.
  • Or open the original via zencreator_get_asset_download_url (presigned). For many assets at once, use the batch variants (zencreator_get_asset_preview_urls / zencreator_get_asset_download_urls).

See ./tools/assets.md.

Response got truncated#

Symptom. A long tool response ends with a truncation note saying to paginate or switch format.

Cause. Text responses larger than ~25,000 characters are trimmed to keep the payload manageable.

Fix.

  • For list tools, paginate: pass limit (1-100, default 20) and offset (default 0), then feed the returned next_offset back as offset for the next page.
  • Or set response_format: "json" for a more compact raw payload.
  • Either way, the full data is always in the structuredContent object, so clients with output-schema support already have everything regardless of the text format.

Validation error (HTTP 422)#

Symptom. A tool result says validation failed — commonly on zencreator_create_task or zencreator_run_and_wait.

Cause. Your input didn't match the generation tool's schema (wrong field name, missing required field, an out-of-range value, or an invalid model/enum).

Fix. Re-check your input against the schema. Call zencreator_get_tool_schema for the generation tool you're submitting (e.g. by_prompt, image_editor, faceswap) — it returns the full input/output JSON Schema plus prompt and model guidance. Fix the offending fields and resubmit. See ./tools/generation.md.

A related HTTP 400 (Bad request) has the same remedy: check the input fields against the tool's input schema.

See also#