How Reports Render, and Report Troubleshooting

Last updated

License feature: Reporting Module

How a report is rendered

1. The API loads the saved report.
2. It starts (or reuses) a headless Chromium browser on the appliance.
3. The browser opens the appliance's own print page for the report, /reports/<id>/print, with a short-lived render token and a 5-minute session for the report's creator.
4. The print page fetches the data for tables, crosstabs, KPIs and charts from the server in one call; embedded dashboard widgets fetch their own data.
5. When all data and images have loaded, the page signals it is ready. The browser prints it to PDF (page size and orientation from the report) and/or captures it as a standalone HTML file with styles and images inlined.
6. The file is saved to the reports folder and recorded in History.

A CSV skips steps 2–5: the API runs the same data queries the print page would fetch and writes the rows straight to a file, so CSV export works even where Chromium is missing or slow.

The report text is in the creator's language, or the appliance default language if the creator has none.

Because a real browser renders the page, a PDF looks like the page in the designer. It also means rendering needs Chromium and memory: the browser is started on the first render and stays running between reports, which is noticeable on a the appliance with little RAM.

Configuration

These are environment variables for the API service (in the appliance's .env), not settings in the UI:

Variable	What it does	Default
REPORT_CHROMIUM_PATH	Path to the Chromium or Chrome binary	Auto-detect: /usr/bin/chromium, /usr/bin/chromium-browser, /usr/bin/google-chrome, /usr/bin/google-chrome-stable, /snap/bin/chromium
REPORT_WEB_BASE_URL	Address the browser opens for the print page	http://localhost:<API_PORT> in production (API port 3001 by default)
REPORT_RENDER_TIMEOUT_MS	Time allowed for the page to load and become ready	30000

The Pi installer installs the chromium package.

Troubleshooting

Symptom	Cause	Fix
No Chromium/Chrome binary found for report rendering. Contact Scada.Ink support or your integrator to have it installed on this appliance.	Chromium is missing on the appliance	Contact Scada.Ink support or your integrator to have Chromium installed
Report has no modules. Design the report layout first.	Empty or unsaved layout	Add modules and Save before generating
This report has no Data Table, Crosstab, Chart or KPI Stat module, so there is nothing to export as CSV.	CSV asked for a report made only of headers, text, images, dividers or dashboard widgets	Add a data module, or generate a PDF instead
A CSV opens in Excel as one column	Your Excel uses a semicolon list separator (common in Europe)	Use Data → From Text/CSV and choose Comma as the delimiter
Generate is grayed out in the designer	Unsaved changes	Save first, or Discard to go back to the saved version
Nothing downloads from the Reports tab	The run failed	Read the error notification, or the History → Error tooltip
The PDF shows the login page	The print page could not be reached at REPORT_WEB_BASE_URL	Point it at this appliance's web app, e.g. http://localhost:3001
The PDF says "Report error: Invalid or expired render token"	The render took longer than the token's lifetime, or the API restarted mid-render	Generate again; raise REPORT_RENDER_TIMEOUT_MS on a slow appliance
A dashboard widget is empty in the PDF	The report's creator no longer exists or is inactive; or the widget did not finish loading in time	Recreate the report as an active user; simplify the widget; raise the timeout
A Data Table has fewer rows than expected	It shows at most Max Rows (up to 5,000) for the range	Raise Max Rows or shorten the Date Range
A Chart module looks smoother than the raw data	More than 1,000 raw points per tag, so the points are averages	Shorten the Date Range
A Chart module shows InfluxDB is not available	Historian down	See historian storage
A KPI shows !	The data query failed; the reason is shown under it	Check Data Source and Column
A crosstab shows an error	Missing row/column field, or no value field for sum/avg/min/max	Fill in the fields
"Yesterday" includes the wrong hours	The appliance's time zone is wrong	Set the appliance time zone; ranges use its local time
A module is split across two pages	No page-break control	Move it up or down in the designer
Scheduled email never arrives but Last Run is green	The mail server accepted it, then a later hop dropped or junked it	Check the mail server's logs and the spam folder; Send test email in Settings checks the SMTP settings
Resend daily limit reached (25/day)…	No SMTP host configured	Configure SMTP Email in Settings
The disk is filling	Report files are kept too long	Lower Report files under Settings → Data Retention

See also

• Reports
• Report Module Reference
• Scheduled Report Emails
• Historian Storage, Outages and Retention