Printing
Troubleshooting prints
The most common issues and what to do about them. If your problem isn't here, email help@badgebadger.app and we'll add it.
“Agent print failed — using browser print as fallback”
The browser couldn’t reach the local agent at port 9988. Causes:
- The agent isn’t running. Check the system tray / menu bar.
- The agent was just installed and you haven’t paired it yet. See Pair your computer.
- A firewall or antivirus is blocking
127.0.0.1:9988. Allow the BadgeBadger Print Agent through your firewall. - The PDF you’re trying to print is unusually large (rare). Re-upload the employee’s photo at a sensible size or contact support.
The popup-print fallback works fine in the meantime — just slower and with a visible window flash.
“Pair this workstation first”
The agent is running but your browser doesn’t have an authorised token. Open Settings → Print agents and click Pair this computer ↗ in the agent, OR paste the token manually.
Print succeeds but no card comes out
This is almost always one of three things on Windows:
- SumatraPDF isn’t installed.Stock Windows uses Edge as the PDF handler, and Edge can’t print to a named queue silently. The agent ships SumatraPDF as a sidecar — if you skipped it during install, grab it from sumatrapdfreader.org.
- The wrong printer is selected. Look at the printer picker in the Print button — it should say Print to <your card printer>, not your office laser.
- The printer’s driver isn’t set to CR-80 paper. In Windows Printers, right-click the card printer → Printing Preferences → set Paper to
Custom 85.6 × 54 mm.
“Failed to fetch” for specific employees but not others
This usually means an oversized photo on that specific employee record. Phone-uploaded photos can be 3–5 MB; the agent body limit and Chrome’s local-fetch handling can choke on those. Re-upload the photo and we’ll resize it server-side (anything bigger than 800 KB gets shrunk automatically).
Photo doesn’t show on the card
Two common causes:
- The template’s photo layer has the wrong binding. In the template editor, click the photo layer and check that Source is set to
employee photo. - The signed URL for the photo or background expired. We auto-heal these now, but on rare occasions a backfill is needed. Email support and we’ll run it for you.
Remote print job stuck on “Queued”
The target workstation’s agent isn’t polling. Check:
- Is the agent actually running on that machine?
- Look at Settings → Print agents → Paired computers and check the “last seen” column. If it’s > 5 minutes, the agent is offline.
- Walk over and restart the agent (or have whoever’s at that workstation do it).
macOS Gatekeeper blocks the agent
First-launch warning is expected since we don’t pay for Apple notarisation yet. Right-click the agent in Applications and choose Open; macOS will let you bypass once.