Troubleshooting the connector

"No print agent is running on this computer"

• The app is not started. Look for the "V" icon in the tray or menu bar; open it from the Start menu or Applications.
• The page is open on a different computer than the one running the agent. Pairing has to happen on the agent's computer; printing afterwards works from anywhere.
• The browser blocks the localhost call. Safari treats http://127.0.0.1 from an HTTPS page as mixed content; use Chrome, Edge or Firefox for the pairing step.
• Something else uses port 41780. Run the headless agent with --port and set PRINTING_LOCAL_AGENT_URL on the server, or free the port.

"The agent on this computer is paired with another server"

The app was connected to a different Vroum before, or to a shop this user cannot see. Choose Unpair from server in the tray menu, then Connect this computer again.

The computer shows as offline

Offline means no heartbeat in the last printing.online_threshold_minutes (10). Check the tray status line:

• Reconnecting… — the WebSocket cannot reach Reverb. Verify the host and port the server hands out (PRINTING_WEBSOCKET_*) are reachable from the shop's network, and that the shop firewall allows outbound WebSocket traffic on that port.
• Not paired — the token was rejected. The computer was probably removed from the shop; pair it again.

Copy status in the tray menu gives the raw state, and Show logs opens the file with the connection errors.

A job stays "Sent to computer"

The server broadcast it but no agent acknowledged it. The agent is offline; the job prints when it reconnects, for up to printing.delivery_window_hours (24). After that it is left alone, on purpose: an invoice printed a day late surprises more than it helps. Print it again.

A job is "Failed"

The error column on Settings › Printers › Recent print jobs holds the reason:

Error	Cause
lp: The printer or class does not exist.	The printer was removed or renamed on the computer. Its list refreshes on the next heartbeat; pick it again in the defaults.
Download failed with HTTP 404	The file was already deleted (a duplicate delivery after the job finished) or the server's disk lost it.
Nothing to print: the document this job points at is gone.	The work order was deleted between the click and the render.
A Chromium or Browsershot message	Rendering failed on the server; see config/browser-shot.php and the Chromium container.

Nothing prints but the job says "Printed"

printed means the operating system accepted the job. Check the OS print queue on the agent's computer: the printer may be paused, out of paper, or set to hold jobs. On macOS, lpstat -p shows the queue state.

The app does not update

• macOS: unsigned builds cannot update. Check the release was built with the signing secrets (see Releases).
• The GitHub Release is still a draft.
• The computer cannot reach github.com. The tray menu shows Update failed: … with the reason after Check for updates.

Running the agent headless

Servers or kiosks without a desktop session can run the CLI build instead of the app: see the connector's README for node bin/vroum-connector.js and the launchd / Task Scheduler snippets. The config file ~/.vroum-connector/config.json is shared with the desktop app.