Troubleshooting
Designer#
| Symptom | Cause and fix |
|---|---|
Console: [report-designer] could not load font manifest from …, empty font list, preview fails | font-base-url doesn't point at the served fonts/ folder. Check the URL in the network tab (Install) |
| Element is empty / zero height | Give it, or its container, a height. It fills its parent |
The template shows [object Object], or nothing loads | You set template as an attribute. Set it as a property (el.template = obj, Vue .prop, Angular [template], React ref) |
| Edits are lost when the parent re-renders | Your framework re-sets an old template object. Keep the latest one from template-change in state (two-way binding), and the designer ignores equal templates |
template-change fires after loading | It doesn't, since loads never fire it. Check whether your code calls a toolbar action, or replaces the template from a template-change handler with a different object |
| Help drawer says "The help content could not be loaded." | Standalone bundle: report-designer.help.js isn't served next to report-designer.js. Bundler builds: the lazy help chunk wasn't deployed with the rest of your build output |
| Import PDF says "The PDF could not be imported: … dynamically imported module" | Standalone bundle: report-designer.pdf.js and report-designer.pdf-worker.js aren't served next to report-designer.js |
| Import PDF brings in garbled text, or no text and only a tracing image | The PDF has no usable text: a scan, text converted to outlines, or fonts without a character map. Trace over the tracing image (user guide) |
Help drawer is blank or 404 with help-base-url set | The override points at the wrong place (the server answers 404 at /help/ when RD_SERVE_DOCS=false), or your app's CSP frame-src or the service's RD_HELP_FRAME_ANCESTORS blocks the iframe. Remove help-base-url to use the built-in guide |
| Previews show a "PREVIEW" watermark | By design: designer previews are for checking the layout. Final PDFs come from the render API, which watermarks only without a valid license (License) |
| Preview is slow and the page freezes during it | The preview worker didn't start (CSP worker-src, or the standalone worker file is missing), so it runs on the main thread. Check designer.renderInWorker |
| CSP violations for inline styles | style-src 'unsafe-inline' is required (Install) |
| Angular: "'report-designer' is not a known element" | Add CUSTOM_ELEMENTS_SCHEMA to the component (or NgModule) |
Angular build warns about pako / budget exceeded | Add "allowedCommonJsDependencies": ["pako"], and raise the initial budget or lazy-load the editor route |
| Vue warns "Failed to resolve component: report-designer" | Set compilerOptions.isCustomElement in the Vue plugin (Vue) |
Render API#
| Symptom | Cause and fix |
|---|---|
400 invalid-template | Read issues[] (path and message). The template is incomplete or out of bounds. Validate on save with /api/v1/validate |
| PDF has empty fields | X-Render-Warnings > 0, or the data doesn't match the bindings. Render with ?format=json and read warnings. Compare the data with the data contract |
| Wrong times on documents | The data has date-times with Z or an offset, converted to the server's time zone. Send local times without a zone (Data contracts and JSON Schema) |
| Images missing, warning "remote/file sources require …" | Remote images are off. Send data URIs, or add the host to RD_IMAGE_URL_ALLOWLIST |
| 413 | The request is over RD_BODY_LIMIT_MB, usually because of large embedded images. Shrink them or raise the limit |
503 server-busy | Capacity reached. Retry after Retry-After, add instances, or raise RD_MAX_CONCURRENCY / RD_MAX_QUEUE |
504 render-timeout | A huge document, or a long queue. Check /ready capacity, and consider splitting batches |
422 render-memory-exceeded | Very large images or tables. Reduce them, or raise RD_WORKER_MAX_MEMORY_MB (and the container memory) |
| Watermarked PDFs in production | X-License-Status isn't valid. Check the Status page or GET /v1/info and the startup log (License) |
| Preview and server output differ | Different versions of designer and server. Upgrade both together (Upgrading and versioning), and make sure server fonts (RD_FONT_DIR) also exist in the designer |
How the samples on this portal are verified#
node docs/developer-guide/check-samples.mjs extracts the code blocks of the portal's pages and checks them:
| Block | Check |
|---|---|
TypeScript (ts check) | Type-checked with tsc --strict against the published @rd/designer declarations (packages/designer/dist/types) |
React (tsx check-react) | Type-checked with React 19's types in the examples/hosts/react app |
Vue (vue check-vue) | Type-checked with vue-tsc in the examples/hosts/vue app |
Angular (ts check-angular) | Compiled with the Angular compiler (ngc, strictTemplates) in the examples/hosts/angular app |
Plain HTML (html check-browser) | Loaded in headless Chromium with the standalone bundle. The element must upgrade, load the template from the stubbed /api/templates/bol and render it on the canvas |
curl (bash run) | Executed against a freshly started render service. Every PDF written must start with %PDF |
Node (js run) | Executed with Node.js against the service. js check-syntax blocks are syntax-checked only (node --check) |
Python (python run) | Executed with requests against the service |
Java (java run, java run-spring) | Compiled and executed with JDK 21 single-file launch, with Jackson and Spring Web on the class path |
C#, Svelte, json, yaml, ini, nginx | Not executed (no .NET SDK or Svelte toolchain in the verification environment). Review them manually |