Troubleshooting

Start with the agent's own view:

jodaprint-agent status

It shows the service state, the activation, the local port, the queue and every printer with its state and problem. Logs are in:

System	Logs
Windows	C:\ProgramData\JodaPrint\logs
macOS	/Library/Application Support/JodaPrint/logs
Linux	/var/lib/jodaprint/logs

From the tray, Send logs uploads them to your dashboard (Devices → device → Logs), where support can read them.

Certificate warnings

The SDK error AGENT_CERT_UNTRUSTED means the agent runs but the browser does not trust its local certificate.

1. Open https://localhost:8182/v1 in the same browser. A certificate warning confirms the problem.
2. Reinstall the trust: jodaprint-agent cert install as administrator or root (the installer runs it too).
3. Restart the browser completely.

jodaprint-agent cert status shows the CA, the certificate and its expiry. The certificate renews itself 30 days before it expires.

Firefox

Firefox uses its own certificate store. On Windows and macOS, turn on security.enterprise_roots.enabled in about:config (or by policy, Certificates → ImportEnterpriseRoots), then restart Firefox.

Linux browsers

Chrome and Firefox on Linux read the user's NSS database, not the system store. Import the agent's CA into it, or use a policy to trust it.

Chrome "Local network access" prompt

Recent Chrome versions ask the user whether a website may connect to devices on the local network, including localhost. Click Allow. Administrators can allow your origins in advance with Chrome's LocalNetworkAccessAllowedForUrls policy.

The agent is not found

AGENT_NOT_FOUND: no agent answers on any port.

• Check that the service runs: jodaprint-agent status, or Services → JodaPrint on Windows.
• The Android agent has no wss://localhost; use the WebView shell.
• Another program may use the ports: see Ports.

Ports

The agent listens on the first free port of 8182, 8283, 8384, 8485, on 127.0.0.1 and ::1 only. The SDK tries them in the same order. If all four are taken, change local.ports in the config and pass the same list to the SDK.

On Windows, netstat -ano | findstr 8182 shows which process uses a port.

Antivirus and firewalls

• Allow jodaprint-agent.exe (Windows) in your antivirus. Some products block programs that listen on a local port or install a certificate.
• The agent only needs outbound HTTPS (port 443) to the cloud. Behind a proxy, set HTTPS_PROXY for the service.
• Network printers need port 9100 open between the computer and the printer.

Printer offline

The job fails with PRINTER_OFFLINE (retried automatically, up to 5 attempts).

• USB: check the cable and power, then jodaprint-agent status.
• Network: ping the printer's IP. Give printers a fixed IP (DHCP reservation), because a new address breaks the printer's identity.
• Windows spooler printers: the status comes from the spooler; clear stuck jobs in the Windows print queue.
• Bluetooth: pair the printer in the OS first, and keep it within range.

PAPER_OUT and COVER_OPEN are retried too, so the receipt prints once the problem is fixed.

Accents print as wrong characters

Thermal printers use codepages, not UTF-8.

1. Use a receipt or text job: the agent converts the text. Raw and ESC/POS jobs are sent unchanged.
2. Set codepage to CP858 (French, Creole and the euro sign) in the document, the job options or printers.defaults.
3. Clone printers sometimes number their codepage tables differently. Try CP850, then CP1252. Print the printer's self-test page (hold the feed button while switching it on) to see its tables.

Jobs print twice, or not at all

• Always send an idempotencyKey (for example the order number). The same key within 24 hours returns the first job and prints nothing.
• A cloud job for an offline device waits up to its TTL (24 hours by default), then fails with TIMEOUT.
• On the free plan, a month's job limit returns LICENSE_LIMIT.

Still stuck?

Send the logs from the tray and contact support with the job ID or the requestId from the error.