Monitoring and troubleshooting
The headless service has no window, so it reports through log files, the Windows event log and an optional local health endpoint. For support cases it bundles everything into one diagnostic package.
Log files
data\logs\veloxprint-20260925.log
data\logs\veloxprint-20260925_001.log same day, after the size limit
data\logs\veloxprint-20260925.json optional, logging.jsonFile
data\logs\lager-nord\veloxprint-... instance with --config lager-nord.json
2026-09-25 07:16:48.120 +02:00 [INF] [Print] [#35] Task #35 received (WebSocket, Standard) -> WH-LABEL-01, 1 copy
2026-09-25 07:16:49.402 +02:00 [INF] [Print] [#35] Task #35 spooled to WH-LABEL-01, 1 page
2026-09-25 07:16:49.655 +02:00 [INF] [API] Task #35 confirmed as printed
Format: time with offset, level (VRB, DBG, INF, WRN, ERR, FTL), area (API, WS, Print, Engine), task id where known, message.
- One file per day, a new file (
_001,_002) whenlogging.maxFileSizeMb(250 MB) is reached. - Files older than
logging.retentionDays(30) are deleted, by age, not by count. - Lines of a task carry its task id and trace id; the trace id links it to the history record and print task in VeloxFactory.
- The API token never appears in any log.
Windows event log
Warnings and errors go to the event log Application, source VeloxFactory Print Service, with fixed event ids for monitoring systems such as Checkmk, PRTG, Zabbix or SCOM. The source is registered when the scheduled task is set up; without it the event log output stays off. Switch it off with logging.eventLog.
| Event id | Meaning | Action |
|---|---|---|
| 1000 | Engine started | |
| 1001 | Engine stopped | Unexpected outside updates and reboots |
| 2000 | API not reachable | Network, DNS, proxy, VeloxFactory up? |
| 2001 | API token rejected (401/403) | Token revoked or rights missing, enter a new token |
| 2002 | Rate limit reached (429) | Occasionally harmless. Often: raise API_RATE_LIMIT_PER_MINUTE or the poll intervals |
| 3000 | WebSocket down longer than 5 minutes | Reverb, firewall, host, port, app key. Hybrid keeps printing by polling. |
| 4000 | Print failed | Error text contains the category |
| 4001 | Printer missing | Install machine-wide or set an alias |
| 5000 | Configuration invalid | A changed configuration was not applied, the engine keeps the last valid one |
Local health endpoint
Optional, switched on under Settings → Operation (health.enabled, port health.port, default 8765). It listens only on 127.0.0.1, needs no URL reservation and no administrator rights, and is not reachable from other machines. A monitoring agent on the same machine polls it.
GET http://localhost:8765/health
{
"status": "ok",
"engine": "Running",
"hostMode": "Headless",
"version": "2.0.1",
"startedAt": "2026-09-25T05:01:12+00:00",
"api": {
"state": "Ok",
"lastApiSuccess": "2026-09-25T07:16:49+00:00",
"lastApiError": null,
"rateLimit": { "limit": 60, "remaining": 58, "rateLimitedUntil": null }
},
"websocket": { "state": "Subscribed", "since": "2026-09-25T05:01:14+00:00", "reconnectAttempt": 0 },
"queue": { "active": 0, "waiting": 0, "retrying": 0, "outbox": 0 },
"printers": { "ok": 3, "withProblems": 0 }
}
| HTTP status | Condition |
|---|---|
200, "status": "ok" | Engine running or paused, and API state OK, unknown or rate limited |
503, "status": "degraded" | Everything else, e.g. token rejected or API unreachable |
| no answer | Engine not running |
Worth alerting on besides the status: queue.outbox above 0 for a longer time (printed but not confirmed), queue.retrying above 0 (printer problem), printers.withProblems above 0, websocket.state not Subscribed.
Diagnostic package
Info → Create support package, or --support-package C:\Temp\support.zip. The ZIP contains:
versions.txt | Program version, machine, account, Windows, .NET, configuration path, whether a token is stored |
config.json | Configuration, anything resembling a token removed |
engine-status.json | Last engine status (as in the health endpoint) |
printers.txt | Local printers with scope, queue state, jobs, driver and driver version, port, dialog flag |
journal-last-500.csv | The last 500 jobs of the journal |
outbox.csv | Open confirmations and error reports: task id;kind;attempts;next attempt;last error. Empty is the normal case. |
config-changes.csv | Last 500 configuration changes: time, account, changed keys |
scheduled-task.txt | XML definition of the scheduled task |
logs/ | The 7 newest log files |
The API token is removed from every file.
Common problems
| Symptom | Cause and fix |
|---|---|
| Tasks stay pending, nothing in the log | Broadcast id of the task is not in receive.broadcastIds, or the task has none and includeWithoutBroadcastId is off. Processing paused? Engine running (dashboard, Task Scheduler)? |
| Tasks are printed, but only after a minute or two | Tasks without broadcast id: VeloxFactory sends no event for them, only the poll finds them. Give them a broadcast id. Otherwise the WebSocket is not subscribed: check the WebSocket tile and Test connection (host, port, scheme, app key, firewall). A token without report-print-task:read fails at the channel authorization. |
Prints from the window, fails from the scheduled task with PrinterNotFound |
Printer only connected for your user profile. Install it machine-wide (Printers and printing). |
| Network printer fails from the scheduled task | Task set up without stored password, or a local account against a domain print server. Use a domain account and set up the task again. |
Error [Timeout] after 120 s |
Printer opens a dialog (PDF printers, OneNote, fax), or the driver hangs. Check the hint on the Printers page. |
| Only one copy instead of n | Driver ignores the copy count. Set Copies to One job per copy for this printer. |
| Output shifted, cut off or too small | Check scaling (Actual size for labels), paper size of the driver and auto rotate. The frame of the test page shows margins and scaling. |
| Very thin or missing lines | Lines with width 0 in the report. Set lineWidth in the JRXML. |
| Printed, but pending in VeloxFactory | Confirmation in the outbox (Queue tile to confirm, outbox.csv). The column last error names the reason. The task is not printed again, the confirmation follows as soon as the API answers. |
| Task shows error Print state unknown after service restart | The service ended while the task was printing. Check the printer; if nothing came out, use Print again. |
| Many 429 / event 2002 | Several services or scripts behind one IP share the limit. Raise API_RATE_LIMIT_PER_MINUTE, use Hybrid instead of short polling intervals. |
| Scheduled task shows result 0x1 / 0x3 | Exit code 1 configuration invalid, 3 token rejected. Start the window or --validate-config. |
| Window cannot save settings | No write access to the data folder. Use Restart as administrator. |
update.ps1 refuses to update |
Local changes in app\, or a window of the Print Service is still open under another user. Close it and run the update again. |