Reliable PDF Reports Need Deterministic Charts and Data

Charting libraries are not unreliable by design. They are asynchronous by design. Most modern charting libraries load data, initialize on a DOM event, wait for font loading, and render through requestAnimationFrame or similar timing mechanisms. This behavior is correct for interactive web pages. It is fragile in a headless rendering pipeline.

The rendering lifecycle in a headless browser follows a sequence:

1. The HTML page is constructed.
2. External scripts and stylesheets load.
3. The page executes JavaScript to build the chart.
4. The chart library performs asynchronous layout and drawing.
5. The PDF renderer snapshots the page.

Step five can occur before step four completes. Font loading, in particular, is a common failure: the chart's layout engine calculates dimensions using font metrics, but if the custom font has not finished loading when the calculation runs, the layout can collapse or produce empty output.

Hosted chart services solve the build problem but introduce others. The rendered PDF now depends on an external network request. If the chart service is slow, the request times out. If it is rate-limited, charts appear blank. If the data is sensitive, sending it to a third-party endpoint raises security questions that legal and compliance teams need to answer.

A rendering pipeline whose output silently depends on network latency, font loading, and browser timing is not a pipeline. It is a nightly gamble.

If the report needs a five-year column chart with fixed axis labels, gridlines, and annotated values, the entire chart can be expressed as inline SVG. No JavaScript. No font loading. No external requests. No asynchronous rendering lifecycle.

The chart becomes part of the HTML document itself, generated server-side and rendered by the same engine that handles the surrounding text and tables. If the PDF renderer can draw a table, it can draw this chart.

For a five-year column chart, the required elements are modest:

• an SVG container with fixed dimensions
• axis lines and gridlines
• five columns with heights proportional to the data
• labels for years, values, and units
• optional annotation text

Each element is a deterministic function of the input data. The column height is a percentage of the maximum value scaled to the chart area. The year labels are strings from the data itself. The value labels are the same numbers formatted for display.

Consider a typical implementation. The data arrives as an array of { year, value } objects. The rendering code calculates the maximum value, maps each value to a pixel height, and emits SVG path and text elements. The output is plain XML embedded in the HTML.

function renderColumnChart(data, width, height) {
  const max = Math.max(...data.map(d => d.value));
  const chartHeight = height - labelSpace;
  const barWidth = (width - padding * 2) / data.length;

  let svg = `<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">`;

  data.forEach((d, i) => {
    const barHeight = (d.value / max) * chartHeight;
    const x = padding + i * barWidth;
    const y = height - labelSpace - barHeight;

    svg += `<rect x="${x}" y="${y}" width="${barWidth * 0.7}" height="${barHeight}" fill="#4A90D9"/>`;
    svg += `<text x="${x + barWidth * 0.35}" y="${height - labelSpace + 20}" text-anchor="middle">${d.year}</text>`;
    svg += `<text x="${x + barWidth * 0.35}" y="${y - 8}" text-anchor="middle">${d.value}</text>`;
  });

  svg += `</svg>`;
  return svg;
}

This function does not need a browser event loop, a layout engine, or a network connection. It needs input data and string concatenation. The PDF renderer treats the resulting SVG exactly as it treats any other static document element.

Where this works well

Hand-drawn SVG is the right choice when:

• The chart is simple. A small number of series, fixed axes, and predictable labels. If the chart is a five-year column chart, it is simple.
• The output is a document, not an interface. PDFs and printed reports are static. Interactivity is irrelevant.
• The data volume is low. Drawing a few hundred SVG elements is trivial. Millions of points would be a different problem.
• Regression risk matters. A deterministic chart either renders correctly or fails visibly. There is no silent blank output.

Where it is not the right choice

Interactive dashboards remain the domain of chart libraries. Hover states, zooming, panning, and dynamic filtering cannot be replaced with static SVG. A BI tool with user-driven exploration should use a proper charting library. The hand-drawn approach is a document-generation decision, not a general front-end strategy.

Similarly, charts requiring complex layouts — multi-series stacked areas with custom legends and intricate axes — become tedious to maintain as hand-coded SVG. The line between "simple enough to hand-code" and "complex enough to justify a library" is crossed quickly. If the chart needs more than one series, a custom legend, or gridline calculations beyond simple division, pause before committing to the manual approach.

Drawing charts by hand solved the rendering problem. It also exposed the next failure layer: the content going into those reports.

Chart data in these reports originated from structured sources — a financial model, a data warehouse, a scenario engine. For a period, that data was sent to an LLM alongside a prompt like "generate a 5-year column chart for the revenue projection section." The LLM was then asked to return JSON representing the chart.

This design has a critical flaw: the LLM's output is a probabilistic string. It may produce valid JSON. It may produce JSON with a trailing comma. It may wrap the JSON in markdown code fences. It may truncate mid-object. And the chart is the one component in the report that cannot tolerate a parsing error — every other section can absorb imperfect prose, but a chart with a missing data point is a wrong chart.

Even when parsing succeeded, another problem appeared: placeholder text. An LLM given a template like {{REVENUE_PROJECTION}} occasionally emits the placeholder string instead of the value it is meant to replace. The report then contains the literal text {{REVENUE_PROJECTION}} in what should be a financial table. To a reviewer, that is not a subtle formatting issue. It is a visible failure that undermines confidence in the entire pipeline.

The fix was to stop treating the LLM as a data-transformation layer. The LLM does not need to calculate chart coordinates. It does not need to format numbers. It does not need to produce structured data at all — unless its task genuinely is structured data production.

The pipeline that works treats the LLM as a narrative generator and treats everything else as deterministic code.

The flow looks like this:

1. Structured data layer. The financial model or data warehouse produces chart values as well-formed data — objects with typed fields, validated before they enter the pipeline.
2. Deterministic chart generation. Code converts the structured data into inline SVG. No LLM involvement.
3. Narrative generation. The LLM receives the same structured data and writes the surrounding prose. It is asked to reference "the revenue projection" — not to reproduce the numbers in a format the pipeline must parse.
4. Validation gates. Before PDF rendering, the pipeline checks for known failure patterns: placeholder strings, incomplete templates, and structural anomalies. Failed components are regenerated or flagged, not silently passed through.

The benefit of this separation is that each stage can fail loudly and be corrected without cascading. If the LLM produces weak prose, the report needs a rewrite, but the charts remain intact. If the data changes, the charts regenerate deterministically while the narrative is regenerated to match.

Validation that catches real failures

The validation layer deserves as much engineering attention as the generation layer. Two checks matter most:

Schema validation for any LLM-produced data. If the LLM must return structured data — for a table, a metadata block, or a config object — validate it against a schema before accepting it. Reject on any violation. Do not attempt to repair invalid output with regex or string manipulation; that path leads to fragile code that works for the first six error patterns and fails on the seventh.

Placeholder scanning for all generated text. Scan the final document for literal template tokens before rendering. A simple check for {{ and }} catches placeholder leaks that would otherwise ship to clients or investors.

These checks are cheap. They run in milliseconds. The alternative — discovering a placeholder token in a finished PDF during QA — costs far more in human attention and re-run time.

What "good" looks like

The operational difference is visible in the failure modes that disappear:

• No timing-dependent blank charts. The SVG is part of the document. If it is in the HTML, it renders.
• No silent parsing failures. Data flows into the chart generator as typed values, not as a string to be parsed.
• No placeholder leaks. The validation gate catches template tokens before rendering.
• Reproducible output. The same input data produces the same chart, every time. Debugging a wrong chart is a data problem, not a race condition.
• Deterministic debugging. When a chart is wrong, the cause is in the data or the mapping logic — never in an external service's rendering behavior.

The overall effect is a report pipeline with fewer moving parts and clearer failure boundaries. Each step is either deterministic code or a validated LLM output. There is no third category of "sometimes works depending on font loading."

This approach is a decision about where to accept risk. The hand-drawn SVG approach accepts maintenance cost in exchange for rendering reliability. Chart libraries accept rendering risk in exchange for richer visualization capabilities.

The LLM separation accepts reduced flexibility in exchange for output reliability. A single LLM call that produces a complete report section is more sophisticated in principle, but it couples every failure mode in one step: one malformed JSON object takes down charts, tables, and prose together.

There is also a cost to consider in aesthetics. Hand-drawn SVG charts look functional, not polished. If the report's visual identity depends on chart animations, gradients, or interactive tooltips — features that make no sense in a static PDF anyway — the library is the better tool. For straightforward data display in a document, the functional look is usually a feature, not a defect.

The same reasoning applies to any automated document generation pipeline:

• Quarterly business reviews with standardized KPI charts
• Compliance reports that must render identically every time
• Client-facing statements with fixed layouts and regulated data
• Operational reports generated in bulk across many accounts

The principle generalizes: if a component can be expressed as a deterministic function of known data, prefer deterministic generation over probabilistic generation or third-party rendering. Save the probabilistic tools for the parts of the output where variability is the point — narrative, summaries, and recommendations.

If your document pipeline produces occasional blank charts, placeholder text, or unparseable output, start by mapping where the nondeterminism enters. Look for three patterns:

1. Rendering dependencies. Does the chart depend on JavaScript execution timing, font loading, or network requests at render time?
2. LLM-produced structural content. Is the LLM generating data that must be parsed and validated instead of generating narrative?
3. Missing validation gates. Does the pipeline check its own output for known failure patterns before the finished document ships?

Most teams find the failure points quickly once they ask which components are truly deterministic and which ones merely pretend to be. Replacing the fragile components with deterministic code — and adding validation where probabilistic output must be used — removes the highest-risk failures from the pipeline without a complete rebuild.