Debug Mode

The problem

PDF generation debugging is hell. Your PDF looks wrong, and you have no idea why. Is it a missing font? A broken image? JavaScript timing? CSS that works in Chrome but not in print mode? Debug mode tells you exactly what happened.

Enabling debug mode

Pass debug: true on any PDF creation or template render request:

curl -X POST https://api.pdfbase.dev/v1/pdfs \
  -H "Authorization: Bearer pk_live_xxx" \
  -d '{
    "html": "<!DOCTYPE html>...",
    "debug": true,
    "output": "url"
  }'

What you get

The response includes a debug object alongside the normal PDF output:

{
  "id": "pdf_debug1",
  "status": "completed",
  "url": "https://files.pdfbase.dev/pdf_debug1.pdf?token=sig_abc",
  "debug": {
    "screenshot_url": "https://files.pdfbase.dev/debug/pdf_debug1.png",
    "console": [
      { "level": "log", "message": "Chart rendered in 342ms" },
      { "level": "warn", "message": "Font 'CustomBrand' not found, falling back to 'Inter'" },
      { "level": "error", "message": "Failed to load resource: net::ERR_NAME_NOT_RESOLVED" }
    ],
    "failed_resources": [
      {
        "url": "https://cdn.broken.com/logo.png",
        "type": "image",
        "status": null,
        "error": "net::ERR_NAME_NOT_RESOLVED"
      },
      {
        "url": "https://fonts.slow.com/custom.woff2",
        "type": "font",
        "status": null,
        "error": "timeout (resource_timeout: 10000ms)"
      }
    ],
    "page_metrics": {
      "dom_content_loaded_ms": 120,
      "load_event_ms": 890,
      "network_idle_ms": 1240,
      "total_resources": 14,
      "loaded_resources": 12,
      "failed_resources": 2
    }
  }
}

screenshot_url

A full-page PNG screenshot of the rendered page, exactly as Chromium saw it before PDF capture. Compare this to your PDF to spot discrepancies.

console

All console.log, console.warn, and console.error output from the page. Invaluable for debugging JavaScript-heavy PDFs (charts, dynamic content).

failed_resources

Every external resource that failed to load: images, fonts, stylesheets, scripts. Each entry includes the URL, resource type, HTTP status (if any), and the error.

page_metrics

Timing breakdown of the render. Useful for identifying slow assets.

When to use debug mode

Development: Always. It costs nothing extra and saves hours of guessing.
Production: Conditionally. Enable for the first N renders of a new template, or when a customer reports issues.
CI/CD: Enable in test pipelines to catch rendering regressions.

Debug output expires with the PDF. If you need to retain debug info longer, download the screenshot and log it yourself.

Request replay

Every API request is logged in the dashboard with its full input: HTML/URL, options, template data, headers. This log persists even after the generated PDF expires.

How it works

Open the Request Log in your dashboard.
Find the request (filter by template, date, status, or metadata).
Click Replay to re-execute the exact same request.
The replay automatically enables debug: true, so you get a screenshot, console output, and failed resource list — even if the original request didn’t have debug enabled.

Why this matters

A customer reports “my invoice looks wrong.” Without replay, your debugging workflow is:

Ask them for the data they sent
Try to reproduce locally
Realize your local Chromium is a different version
Give up and add debug: true to production
Wait for it to happen again

With replay:

Find the request in the dashboard
Click Replay
See exactly what went wrong (screenshot + console + failed resources)
Fix it

This turns a multi-day support thread into a 2-minute investigation.

Replay via CLI

# List recent requests
pdfbase requests list --limit 10

# Replay a specific request with debug output
pdfbase requests replay req_abc123

Replay via API

curl -X POST https://api.pdfbase.dev/v1/requests/req_abc123/replay \
  -H "Authorization: Bearer pk_live_xxx"

Returns the same response as the original endpoint, with debug info included.

Get Started

Core Concepts

Guides

Integrations

Resources

The problem

Enabling debug mode

What you get

screenshot_url

console

failed_resources

page_metrics

When to use debug mode

Request replay

How it works

Why this matters

Replay via CLI

Replay via API

​The problem

​Enabling debug mode

​What you get

​screenshot_url

​console

​failed_resources

​page_metrics

​When to use debug mode

​Request replay

​How it works

​Why this matters

​Replay via CLI

​Replay via API

The problem

Enabling debug mode

What you get

screenshot_url

console

failed_resources

page_metrics

When to use debug mode

Request replay

How it works

Why this matters

Replay via CLI

Replay via API