# Troubleshoot common problems

Troubleshoot render failures, missing data, blocked images, and page breaks.

## Preview works but render does not
Check published version, key/project, `template:render`, quota and preview resource warnings. Preview can omit disallowed images while a real render rejects them.

## Identify the error before retrying

| Code or symptom | Action |
| --- | --- |
| `PDF_TEMPLATE_VERSION_NOT_PUBLISHED` | Open the target version in the editor and Publish it, then retry the job. |
| `PDF_INVALID_API_KEY` / `PDF_API_KEY_INSUFFICIENT_SCOPE` | Check the active key, correct project and `template:render` scope. |
| `PDF_RENDER_QUOTA_EXCEEDED` / `quota_exceeded` | Check workspace usage in Settings. Repeated POSTs do not restore quota. |
| `EXTERNAL_IMAGES_NOT_ALLOWED` | Read the preview warning and [image policy](/docs/assets/images/); use resources allowed by the workspace’s plan. |
| `ASSET_STORAGE_PLAN_REQUIRED` | The workspace cannot currently serve project assets. Check the plan and storage notice in Assets. |
| `RENDER_TIMEOUT` | Simplify or split large content, reduce image work, and check the processing limit before retrying. |
| 404 immediately after render 202 | Keep the accepted render ID and [follow the status retry guidance](/docs/developers/render-reference/). |
| PDF still shows an old label | Save the design, then regenerate PDF preview. Run inputs do not update the editor preview’s values. |

## Missing data
Check names, `params` bindings, prop scope and selected variant. In arrays, inspect item context and the full JSON shape.

## Clipping or excess whitespace
Inspect fixed heights/overflow, margins, fonts and keep-together settings. Start with small input and use PDF preview to locate physical page transitions.

## Download fails
Confirm success, retained output and project authorization. Download URLs do not bypass access controls.

## HTTP 401/403
Check API origin, `ApiKey`, current credential and scopes. A project A key cannot access project B's template. Do not send secrets to support.

## Agent revision conflict
Reread current context and reconcile changes. Do not blindly overwrite a newer revision. Distinguish project `/mcp` from public `/docs/mcp` and use the correct headers.

## Report reproducibly
Provide time, action, template/version, render/delivery IDs and sanitized errors. Prefer fake reproduction data and redact credentials/personal information in screenshots.