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] [API] #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] #35 Task #35 confirmed as printed

One file per day, a new file (_001, _002) when logging.maxFileSizeMb (250 MB) is reached.
Files older than logging.retentionDays (30) are deleted, by age, not by count.
Every line of a task carries its task 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, runtime, Windows, account, paths
`config.json`	Configuration, anything resembling a token removed
`engine-status.json`	Last engine status (as in the health endpoint)
`printers.txt`	Local printers with driver, port, scope and queue state
`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	WebSocket not subscribed, the safety poll finds them. 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.