Troubleshooting

What Is This?

Troubleshooting collects common reasons a template does not render as expected. It focuses on problems a template author can recognize from the XML, data values or visible output.

When Should I Use This?

Use this chapter when a control is missing, an attribute seems ignored, a value prints empty, an image does not appear, or content moves to another page unexpectedly.

How Do I Start?

Start from the symptom:

XML errors usually come from invalid XML syntax or unsupported structure.
Missing visible content may be a data, control or layout problem.
Unexpected page breaks usually need layout and available-space checks.

Each troubleshooting entry links back to the concept or reference page that explains the underlying behavior.

The XML Does Not Load

Check basic XML syntax first:

Every opening element needs a matching closing element unless it is self-closing.
Attribute values need quotes.
Special text characters such as < and & need XML escaping.
Transformer blocks still live inside XML text, so the surrounding XML must remain valid.

If the error mentions an invalid node name, check for a dot in a normal control name. Style nodes are the special case documented in Styles.

A Control Is Unknown

If the error says a control does not exist, check the element name first. Built-in controls are listed in Controls, with focused pages for Rich text, Flow helpers, Lists and Form and signing controls. The compact attribute lookup is in Quick reference. Optional QR and ZXing barcode controls require the package registration documented in QR code control package and ZXing barcode control package.

Common causes:

A typo in the element name.
A custom control that the application has not registered.
An optional control package that the application has not installed or registered.
A template namespace change that prevents the built-in controls from being found.

Developer setup and custom control registration belong in the developer integration appendix.

A Custom Default Namespace Breaks Built-In Controls

The manual examples intentionally omit xmlns. When an element has no XML namespace, the reader treats it as part of the built-in control namespace.

Do not add a custom default namespace to normal templates:

<template xmlns="MyApp.PdfControls">
    <body>
        <text>Hello</text>
    </body>
</template>

In this XML, text is read in MyApp.PdfControls, not in the built-in namespace. The result is usually an unknown-control error for MyApp.PdfControls:text.

Do not try to fix this with a namespace prefix. The XML reader rejects prefixed element names such as default:text, even if the prefix points at the current Papercraft namespace (X39.Solutions.Papercraft) or the legacy X39.Solutions.PdfTemplate.Controls namespace. This remains invalid:

<template xmlns="MyApp.PdfControls"
          xmlns:default="X39.Solutions.PdfTemplate.Controls">
    <body>
        <default:text>Hello</default:text>
    </body>
</template>

For normal authoring, remove the namespace declaration and use unprefixed control names. If a template needs an application-specific control beside built-in controls, ask the application team which unprefixed element name they registered in the normal Papercraft control namespace.

An Attribute Is Rejected

Attributes are not free-form labels. Each control accepts only the parameters implemented for that control.

If an attribute seems to be accepted but has no visible effect, check the focused control page for that attribute. Do not treat ignored attributes as a general fallback behavior; unsupported attribute names are rejected.

Check Controls, the focused control pages and Quick reference for supported attribute names. For package controls, use QR code control package or ZXing barcode control package. For shared spacing, clipping and alignment attributes, see Layout fundamentals.

A Length, Color Or Thickness Value Is Rejected

Layout values are parsed by the type of the attribute. If a control rejects a value such as length, margin, padding, thickness, color, background or foreground, check the value format before changing the surrounding layout.

Common checks:

Lengths can use numbers without a unit, px, pt, mm, cm, in, % or auto.
A number without a unit is pixels, so use 50% for half the available space, not 0.5.
Colors can use names such as red, orange, black, white and transparent, or hex values such as #f00, #ff0000 and #ff000080.
Thickness values such as margin, padding and border thickness take one, two or four lengths separated by spaces. Three values are not supported.
Star widths such as 1* and 2* are table-column values only; do not use them for normal length attributes.

For the full user-facing reference, see Layout fundamentals.

A Control Does Not Allow Children

Some controls are containers and some are leaf controls. For example, border can contain other controls, while text and line render their own content.

If the error says a control does not support child controls, move the child content into a container such as border, table or the document body. For the control-authoring mental model, see Control concepts.

A Value Prints Empty Or Does Not Change

Check the exact variable or function name with the application team. Template data names must match what the application supplies. The Template data chapter covers simple variables and data-backed attributes.

If a text value still shows the @ name, such as @OrderNumber, the XML reader did not find a matching variable.

If an attribute value starts with @ and the variable is missing, the evaluated attribute value becomes empty before control parameter binding. This can later make the control reject the attribute if an empty value is not valid for that attribute type.

Common checks:

Compare the template name with the data name supplied by the application.
Check casing, spelling and underscores.
Do not use @Customer.Name for nested object fields. In text, the dot stops the variable name, so this is read as @Customer followed by literal .Name.
Do not use a text value as an @if condition. Ask for a Boolean flag such as HasOrderNumber, or a Boolean helper function.
For attributes such as color="@AccentColor", confirm that the supplied value is a valid value for that attribute.
Keep a visible fallback label in normal text when missing data would otherwise be hard to notice.

For supported naming patterns, missing-data behavior, optional-value flags and nested-data guidance, see Template data.

A Function Or Transformer Fails

Function calls need a closing parenthesis. Transformer blocks such as @if and @foreach need opening and closing braces. The XML reader has dedicated exceptions for missing function brackets and missing transformer braces.

An unknown function in text, such as @formatTotal(), is reported as a missing function.
An unknown function in an attribute, such as color="@statusColor()", is reported as a failed expression evaluation.
A function call without a closing ) is reported as a missing closing function bracket.

Keep transformer blocks small while debugging. Remove unrelated content until only the failing condition or loop remains, then compare it with Template language.

Common Transformer Mistakes

For @if:

Use @else if, not bare else if.
Put every @else if before the final @else.
Use only one @else.
When there is no comparison operator, the expression must evaluate to true or false.

For @switch:

Put only @case and @default clauses directly inside the @switch block.
Put @default last.
Use @default only once.
Give every @case a value or comparison.

For @for:

Use the form @for Name from Start to End.
Use step only when the loop should skip values.
Use a positive step when counting up and a negative step when counting down.

For @foreach:

The value after in must be a collection supplied by the application or returned by a function.
An empty collection renders no repeated content.
The optional with IndexName part creates a zero-based counter for the block.

An Image Does Not Appear

The built-in image control uses the application resource resolver. The default resolver accepts base64 image data and data:image/...;base64,... values. It does not load arbitrary file paths or internet URLs.

If a template needs file, database, object storage or HTTP images, the application must provide a custom resolver. Ask the application team which image source format is supported for your templates. For the template-author reference, see Image control.

Common checks:

If source looks like https://example.com/logo.png or C:\Images\logo.png, the default resolver rejects it.
If source starts with data:image/, it must include the comma and base64 payload, such as data:image/png;base64,....
If source is plain base64, it still must decode to real image bytes. Base64 text that is not an image fails during image initialization.
If source="@LogoImage" is used, confirm that the application supplies the image value in the format its resolver expects.

A Chart Shows No Data Or Missing Values

Chart data values are parsed as numbers before the chart is drawn. If no usable data remains, line charts and bar charts render a “No Data Available” message. Pie charts show the same kind of message when all y values are missing, invalid or add up to zero or less.

Common checks:

Use 3.5 for decimal values, not a localized decimal comma such as 3,5.
For lineChart and barChart, every visible point or bar needs both numeric x and numeric y values.
For pieChart, every visible slice needs a numeric y value. x is optional for pie slices.
Invalid rows are skipped. One bad data row does not stop the whole chart, but a chart with only invalid rows has no data to draw.
Put data inside lineChart, barChart or pieChart, not directly inside chart.
Bar and line charts do not draw category labels from label, x-label or y-label; use a table when exact labels are required.

For the chart authoring reference, see Chart controls.

Content Moves To Another Page

Content in body is allowed to continue on later pages. This is normal when the arranged body content is taller than the body space on one page. Headers, footers and page margins reduce that body space before the body is drawn.

Use this section when the page break is surprising. Start with Page breaks, then check which rule applies.

Check Available Body Space

Reduce large margin, padding and thickness values.
Check whether a header or footer leaves less body space than expected.
Check page margin in the application or document setup. Page margin is not a body attribute.
Check whether a stretched container is taller than intended. If a border should stay near its content, try verticalAlignment="top".

Check Where The Content Lives

Use normal body content for flowing paragraphs and tables.
Use background and foreground for repeated page-wide marks that should not reserve body space.
Use areas only for fixed-position content that should not affect the body flow. Area content is clipped to the area rectangle and does not push body content to a later page.

Check Tables Separately

Tables have one extra page-break rule. Table body rows are kept together, so a row can move to the next page even when part of the row might have fit in the remaining space. If the table has a th header, the header is rendered again before the moved row.

For table-specific checks, see A table breaks or overflows unexpectedly.

A Table Breaks Or Overflows Unexpectedly

Tables are laid out row by row. TableControl checks the remaining page height before each body row is rendered. When the next row is taller than the space left on the current page, the table advances to the next page and renders the table header again before the row.

Common checks:

Keep table rows reasonably short. A row with several tall cells may move earlier than expected because the whole row height matters.
Put repeated column labels in th so they can appear again after a table page break.
Reduce padding, margins and border thickness inside td contents when only a few rows fit on each page.
Check whether the page header, page footer or document margin has left less body height than the table needs.
Split very large text blocks into more rows before placing them in a table.

If one body row is taller than a full available page, the table does not split that row into smaller row fragments. The row is still moved to a fresh page when it does not fit in the remaining space. If the table has a th header, the header is rendered again before the oversized row. The row then keeps its arranged height, so it can continue past one page of body space instead of behaving like normal flowing body text.

For long readable content, split the content into several rows or move it out of the table into normal body content.

Previous: Complete examples

Manual home

Next: Developer integration appendix