Skip to main content

Troubleshooting

Common issues and how to fix them.

Document Generation​

"Template not found" (404)​

  • Check that the template_id UUID is correct.
  • Confirm you're querying the right environment — a template created in UAT won't appear in Production and vice versa. Pass is_uat=true if using a UAT template.

Document stuck in queued or rendering​

  • This usually means the backend worker is busy. Wait a moment and poll again.
  • If it stays in rendering for more than 2 minutes, check if the template contains a broken Jinja2 expression (unclosed {% if %}, unknown variable in strict mode, etc.).

status: failed with no clear error​

  • Open the document via GET /documents/{id} — the error_message field contains the failure detail.
  • Common causes: malformed Jinja2 syntax, a required token missing from input_json, or an image URL that couldn't be fetched.

PDF Output​

Table borders not showing in the PDF​

TinyMCE inserts tables using the HTML border="1" attribute. Browsers render this automatically, but the PDF renderer (WeasyPrint) requires CSS. DocGenLab handles this conversion automatically — if borders are still missing, ensure you're running the latest backend version.

Content cut off or overflowing a page​

  • Check if your template has very wide fixed-width tables. Use percentage widths (width: 50%) rather than pixel widths.
  • Large images can push content off the page — the system constrains them to max-width: 100%, but very tall images may still cause overflow.

PDF margins look different from the preview​

The live preview and generated PDF both use 20mm margins. If you see a difference, it may be caused by custom inline styles on the <body> element in the template HTML.

Non-Latin characters (e.g., Kannada, Arabic, Hindi) not rendering​

WeasyPrint requires the system font to include the character range. Ensure the server has the appropriate fonts installed (e.g., fonts-noto on Ubuntu). Contact support if this affects your deployment.

Templates​

Variables panel shows wrong type (List vs Text)​

  • DocGenLab auto-detects list variables from {% for x in VAR %} syntax. If the type shows as "Text", open the Variables panel and change the type to "List" manually.
  • After inserting a Loop block with the toolbar button, the variable is registered as "List" immediately. If it reverts to "Text", re-save the template.

Loop block not generating repeated rows in DOCX​

For DOCX templates, the {% for %} tag must be in the first cell of the row you want to repeat, with {% endfor %} in the last cell of the same row. If the tags span multiple rows, docxtpl won't recognise them as a row loop.

Token detected with wrong name (extra underscore, number suffix)​

If you have {{ client name }} (with a space), it is auto-corrected to client_name. The Variables panel will show the corrected key — use that key in your input_json.

Bulk Generation​

Some rows failed — where do I see why?​

Download the result ZIP. It contains an error report Excel file listing each failed row number and the error message for that row.

Excel headers not matching template tokens​

DocGenLab normalises headers (converts spaces to underscores, lowercases). If a column still doesn't match, check that the token name in your template doesn't have unusual characters or capitalisation that the normalisation doesn't handle.

Date values appear as numbers in the document​

Excel stores dates as serial numbers internally. If your date column is formatted as a number in Excel, format it as a Date or Text cell instead.

Authentication​

401 Unauthorized​

  • Confirm the X-API-Key header is present and the value starts with dgl_.
  • Check that the key hasn't been revoked in Settings → Developer.

429 Too Many Requests​

You've exceeded the rate limit (default: 60 requests/minute). Implement exponential backoff — wait 1–2 seconds and retry. See the API Keys guide for details.

Session expired while editing a template​

Your work is auto-saved to browser localStorage every 30 seconds. When you log back in and return to the editor, a banner will appear offering to restore the draft.

Webhooks​

Webhook not being received​

  • Confirm your URL uses HTTPS — HTTP endpoints are blocked.
  • Check that your server is publicly reachable (not localhost without a tunnel like ngrok).
  • Use the Test Webhook button in Settings → Developer to send a test payload and check your server logs.

Receiving duplicate webhook calls​

DocGenLab retries failed deliveries up to 3 times. Use an idempotency check on job_id in your handler to safely ignore duplicates. See the Webhooks guide.

Still stuck?​

Contact support at support@docgenlab.com with your organisation ID and the document/job ID you're having trouble with.