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) when 
logging.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.