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”
The browser couldn’t reach the local agent at port 9988, so BadgeBadger fell back to browser printing (or downloaded the PDF). 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. It’s just slower, with a visible window flash.
“Pair this workstation first”
The agent is running but your browser doesn’t have an authorized token. Open Settings → Printers → 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 to 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 → Printers → Print agents → Paired computersand check the “last seen” time on that computer’s row. 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
The Print Agent is signed and notarized by Apple, so the only prompt you should see is macOS asking you to confirm opening an app downloaded from the internet. If it says “Apple could not verify…” instead, that copy was downloaded before the agent was notarized in October 2026. Delete it and download the agent again from Settings → Printers → One-click printing setup. Full steps: Install the Print Agent.