# PDF render warning codes

Every successful render includes a render report. Each warning in it has a stable code, so your application or your agent can decide what to fix, log or send for review.

## How the report looks

Warnings are in `manifest.warnings` in the answer. Each one has a `code` and a `message`; some also have a `sample`, the text the warning is about.

```json
{
  "status": "succeeded",
  "pdf_url": "https://…",
  "manifest": {
    "warnings": [
      {
        "code": "FONT_FALLBACK",
        "message": "'Times New Roman' is not available; text was rendered with Liberation Serif. Upload the font or use a bundled one."
      }
    ]
  }
}
```

An empty list means no warnings were reported. The report lists the issues Stolid detects, such as missing fonts, blocked requests and overflowing content. It does not catch every layout issue, and some print CSS differences produce no warning: see [Page options](https://stolid.dev/docs/page-options/) and check the PDF as well.

## All warning codes

| Code | What it means | What to do |
| --- | --- | --- |
| `FONT_FALLBACK` | A font you asked for is not available; a similar one was used | Send the font file with the request, or choose an available font |
| `FONT_FACE_FAILED` | A font file you declared with `@font-face` could not be used | Check the font file and its name in `assets` |
| `ASSET_FAILED` | A file was missing from `assets` or failed to load | Add the file, or correct its name in the HTML |
| `REQUEST_BLOCKED` | A file request was blocked | Send remote files in `assets` |
| `CONTENT_OVERFLOW` | Content extends past the page width or a clipping container | Let the content wrap, or reduce its width |
| `SCRIPT_ERROR` | A script in your page raised an error | Fix the script, or remove it from the document |

New warning codes may be added. Codes keep their meaning, so a rule you write today keeps working; treat any code you do not recognise as information.

## Read the codes in your code

With the clients, `render.warnings` (Python) and `getWarnings(render)` (Node) return the list, empty when there are none. An example policy that stops a build when selected warning codes are present:

```python
from stolid_client import StolidClient, WarningCodes

BLOCKING = {WarningCodes.FONT_FALLBACK, WarningCodes.ASSET_FAILED, WarningCodes.CONTENT_OVERFLOW}

with StolidClient() as client:
    render = client.create_pdf(html)

problems = [w for w in render.warnings if w.code in BLOCKING]
if problems:
    raise SystemExit("; ".join(f"{w.code}: {w.message}" for w in problems))
```

## Related

- [Files and fonts](https://stolid.dev/docs/files-and-fonts/): fix `ASSET_FAILED`, `FONT_FALLBACK` and `FONT_FACE_FAILED`.
- [Page options](https://stolid.dev/docs/page-options/): print CSS that the report does not warn about.
- [AI agents over HTTP](https://stolid.dev/docs/ai-agents/): use the codes in a bounded fix-and-retry loop.

Public preview: free while we work with early users. Use sample data; there is no uptime commitment yet.

[Preview Terms](https://stolid.dev/legal/terms/) · [Acceptable use](https://stolid.dev/legal/terms/#acceptable-use) · [Privacy Policy](https://stolid.dev/legal/privacy/) · [Data handling](https://stolid.dev/data/) · Report abuse or copyright infringement: hello@stolid.dev

© 2026 Stolid · Operated by an individual in Washington, USA

Source: https://stolid.dev/docs/warning-codes/
