Connection Refused or Reset

The two failures look similar in a log and mean opposite things. Check which one you actually get.

Connection reset immediately after connecting

The listener accepted you and then dropped the socket. That is the IP whitelist doing its job: the address you connected from is not on the workspace's list, so the connection is reset rather than politely closed.

This is the expected first experience from a second machine, because a new workspace starts with the whitelist enabled and only the IP you created it from on the list. A CI runner, a POS terminal, or your laptop on a different network is a different address.

To fix it:

1. Open Workspace Settings -> IP Whitelist.
2. Add the address, one per line. Exact IPs and CIDR ranges both work (203.0.113.7, 203.0.113.0/24), # starts a comment.
3. Save, and print again.

If you do not know the address to add, Workspace Settings -> Access Log lists every connection the workspace received, rejected ones included, so you can copy the address straight from there.

Turning the whitelist off entirely also works, and is sometimes what you want for a throwaway workspace - but read Documents you did not print first, because the port is reachable from the whole internet.

Connection refused

Nothing is listening. In order of likelihood:

1. The printer is stopped. Its card shows the state; start it from the printer's card or the Operations panel.
2. Wrong port. Each printer has its own; the card shows it, and so does settings.tcpListenPort from the API. See Raw TCP port 9100.
3. Wrong host. virtual-printer.online for the hosted service, your own host if you self-host.

Connection times out

Nothing answers at all, which is a network problem rather than a printer problem. Printer ports are non-standard, and plenty of corporate networks allow outbound 80 and 443 only. If it works from home and hangs at the office, that is the cause - ask for the port to be opened, or self-host inside the network.

To separate the two cases quickly:

# Linux / macOS
nc -vz virtual-printer.online 9411

# Windows PowerShell
Test-NetConnection virtual-printer.online -Port 9411

Still stuck?

Email support@virtual-printer.online with the printer's protocol and port, what your application sent, and what you expected to see.