15. Troubleshooting and FAQ

Data and bindings

A field prints empty in the real PDF.

1. Check the spelling and capitalization of the path. shipTo.Name is not shipTo.name.
2. Check the Fields tab. Is the field there, and at the same level? Inside a table, use item. ({{ item.qty }}, not {{ qty }}).
3. Ask your integrator to confirm that the field is actually sent for this document.
4. Render with ?format=json (chapter 13) and look for an "Expression" warning.

The sample (preview) text printed in a real document. This can't come from a binding's preview text, which real renders always ignore. The text is static: it was typed outside the braces. Compare {{ shipTo.name | Northwind }} (correct) with {{ shipTo.name }} Northwind (prints "Northwind").

The designer shows {{shipTo.name}} instead of a name. The binding has no preview text. Add one: {{ shipTo.name | Northwind Retail #1187 }}. If every binding shows its expression, Show expressions instead of preview text is switched on in the toolbar.

Numbers show many decimals (116.39999999999999). Format them: {{ formatNumber(x, 2) }} or {{ formatCurrency(x, 'USD') }}. See chapter 6.

Dates show the wrong time. Times with a time zone are converted to the render server's time zone. See the warning in Dates and times.

A checkbox is never checked. Text comparisons are case-sensitive and need quotes: freightTerms == 'prepaid', not freightTerms == Prepaid.

Layout

Text is cut off at the bottom of its box. Make the box taller, choose Shrink to fit, or, in the Report Header, Body or Report Footer, turn on Stretch to fit content so the box grows.

Elements overlap after a table grows. Elements below a growing table move down only if they overlap it horizontally, or have nothing above them in their own column (chapter 4). Make sure the element is below the table, not beside it, and that it isn't Pinned.

A frame drawn with a rectangle doesn't grow with its content. Rectangles have a fixed size. Use borders on the text element or the table instead (chapter 4).

The footer covers the last table rows. It can't: the body always stops above the page footer. If text overlaps the footer, it is in the Page Footer band itself, or the element is in the Background band.

A blank page appears at the end. The content just fits, and a report footer or an element with spacing below it moves to a new page. Reduce the report footer's height, or the space under the last element.

The page header is missing on page 1 (or on later pages). Check Print on for the page header (chapter 4).

There is empty space at the bottom of pages before the footer. A page footer set to Last page only or All but the last reserves its space on every page. Use the Report Footer for content that belongs on the last page only.

Page Break doesn't work. Page breaks only work in the Body band.

Fonts

The PDF uses a different font than I chose. The font name isn't one of the bundled or uploaded fonts. The engine uses Arimo instead and warns "Unknown font family '…', using 'Arimo'". Pick a font from the list, or upload the font (chapter 10).

Bold or italic doesn't appear. The family has no such face. For example, Oswald and the Chinese/Japanese/Korean fonts have no italic. The nearest face is used. Upload the missing face if you have it.

Boxes (☐) instead of characters. No bundled font has those characters (for example emoji, or Arabic). Use a font that has them, or remove them.

Japanese text looks "Chinese". Set the Document language to ja-JP (chapter 11).

Barcodes

A barcode is missing in the PDF. The value isn't valid for the format. The warning tells you why, for example "Code 39 must contain only digits, capital letters…", "Incorrect EAN-13 check digit provided", "AI 00: Bad checksum" or "AIs must start with '('". See Barcodes.

A barcode doesn't scan.

• Make it larger, especially taller, or shorten the value.
• Leave blank space left and right, or turn on Quiet zone.
• Use black on white.
• On GS1-128, the parentheses must be in the value: (00){{ sscc }}.
• Print at 100% scale. "Fit to page" in the print dialog shrinks the barcode and the whole page.

Images

An image doesn't appear. If it comes from a web address, the render service fetches it only from sites your administrator allows. Embed the image (Embed image…) or ask your system to send it as data. Very large images (over 25 megapixels) are skipped, so resize them first.

The designer

My changes are gone after reloading. The designer doesn't store templates itself. Use Save (your application stores the template) or Export template JSON.

The canvas looks slightly different from the preview. The canvas is a fast approximation (barcodes are drawn as placeholders, for example). The Preview PDF is exact.

The designer is in the wrong language. The designer's language comes from your application or browser (chapter 11).

What the warnings mean

Warnings are listed under the preview and returned by the render service. A warning never stops the render. The affected element prints empty, or with a fallback.

Errors that stop the render. A template that breaks the rules can't be rendered, and the designer and service list the problems: for example a font size above 1000 pt, a page larger than 200 in (14,400 pt), or more than 10,000 Min. rows. Correct the setting that is named.

FAQ

Can I use the same template for Letter and A4? Yes, but positions don't scale. Switch the page size and check with Preview PDF. Gallery templates are designed to fit both.

How many pages can a document have? The render service allows up to 2,000 pages per document by default. Your administrator can change this (RD_MAX_PAGES).

Can I put a barcode in a table cell? Not directly. Use a Repeater instead (chapter 8).

Can a table sort or group? Yes: Sorting and grouping.

Can I print a document in two languages? Yes. Type both languages in the labels (Bilingual documents).

Is my data stored by the designer or the render service? No. The designer never receives data. The render service uses the data for one render and doesn't store it or log it.