Skip to main content

Document Troubleshooting

Template variables show as {{variable_name}}​

The template contains placeholder variables that weren't replaced during rendering:

  • Variable name misspelled: Check for typos. Variables are case-sensitive and must match the variable reference exactly (e.g., {{visitor_name}}, not {{visitorName}}).
  • Variable not in the supported set: Only the documented variables are available. Custom variable names are not recognized.
  • Offline check-in without cached data: If the kiosk was offline and didn't have the visitor's pre-registration data cached, some variables display as "N/A." The server fills in the correct values when processing the queued submission.

Documents not appearing during kiosk check-in​

  • No templates assigned to the site: Check the site's document assignments in the admin dashboard. A site with zero assigned templates skips the document step entirely.
  • Visitor already signed current version: Returning visitors who have signed the current template version skip that document. This is expected behavior. Check the visitor's profile to see which versions they've signed.
  • Template cache stale: If a template was recently assigned or updated, the kiosk may not have fetched it yet. Wait for the next cache refresh (default: 15 minutes) or restart the kiosk.

PDF not generated after check-in​

PDF generation is asynchronous — it happens in the background after check-in. If a PDF is missing:

  • WeasyPrint sidecar down: Check that the WeasyPrint container is running: docker ps | grep weasyprint. Check its logs: docker logs atrium-weasyprint.
  • Event processing delayed: The PDF is generated in response to a visitor.documents_signed event. If NATS is overloaded or the consumer is behind, there may be a delay.
  • Failed generation: Check the backend logs for WeasyPrint errors. Common causes: invalid HTML in the template (CSS that WeasyPrint can't parse), or the sidecar being temporarily unreachable.

The HTML snapshot and signature data are always stored immediately at check-in. Even if PDF generation fails, the source data is preserved and the PDF can be regenerated.

PDF looks different from what the visitor saw​

The kiosk renders templates in the browser (Chrome/Safari), while the PDF is generated by WeasyPrint (a different rendering engine). Minor differences in CSS interpretation are possible:

  • Fonts: WeasyPrint uses system fonts available in the container. If your template specifies a font not available in the container, WeasyPrint falls back to a default font.
  • CSS features: WeasyPrint supports most CSS 2.1 and some CSS 3 properties, but not all. Complex layouts (flexbox, grid) may render differently. Stick to simple CSS for best fidelity.
  • Page breaks: WeasyPrint handles page breaks differently than browsers. Long documents may paginate differently in the PDF.

The HTML snapshot (the exact content the visitor saw) is always preserved alongside the PDF, providing a faithful record regardless of PDF rendering differences.

Signature appears blank in the PDF​

  • Signature not captured: The visitor may have tapped "Sign & Continue" before actually drawing a signature. The button requires at least one stroke to activate, but very brief touches might register as a minimal stroke.
  • Signature data corrupted: Rare. The signature PNG is embedded in the HTML snapshot submitted by the kiosk. If the PNG data is invalid, the PDF will show a blank signature area. Check the stored signature data in the visit detail view.