Troubleshooting
Installation Issues
macOS: App is "damaged" or from "unidentified developer"
PrintHQ Bridge is not yet notarized with Apple. After installing the .dmg, open Terminal and run:
xattr -cr "/Applications/PrintHQ Bridge.app"Then right-click the app and select Open (not double-click) for the first launch. After the first successful launch, you can open it normally.
macOS: Blank window on first launch
If the app opens but shows a blank white window, try the xattr command above and restart the app. If it persists, make sure you're running macOS 12 (Monterey) or later.
Windows: Installer can't overwrite bridge-server.exe
If the installer fails with a file-in-use error, the previous Bridge process is still running. Open Task Manager, find bridge-server.exe, end the task, then run the installer again.
Windows: SmartScreen warning
Windows may show a SmartScreen warning for the installer. Click More info > Run anyway to proceed. This happens because the installer is not yet signed with an EV certificate.
Connection Issues
Bridge can't find / connect to my printer
- Same network? Make sure Bridge and your printer are on the same WiFi network / VLAN. Printers on a guest network won't be reachable.
- Ping test: Try
ping <printer-ip>from the machine running Bridge. If it doesn't respond, it's a network issue. - Firewall: Check if your computer's firewall is blocking outbound connections on the printer's port.
- Correct IP? Printer IPs can change if your router assigns dynamic addresses. Check the printer's screen for its current IP, or set a static IP / DHCP reservation in your router.
- Use diagnostics: In the Bridge web UI, use the built-in network diagnostics tool to test connectivity to your printer's ports.
Printers on a different VLAN / subnet
If your printers are on a different subnet (e.g., your PC is on 192.168.1.x but printers are on 192.168.2.x), Bridge won't discover them automatically. You can add custom subnets in the Bridge settings:
- Open the Bridge web UI at
http://localhost:9876 - Go to Settings
- Add your printer's subnet to Custom Subnets (e.g.,
192.168.2) - Bridge will now scan that subnet during discovery
TIP
You still need proper routing between subnets for Bridge to communicate with printers. Make sure your router allows traffic between the VLANs.
All printers showing "Unknown" or disconnecting
If all printers suddenly go offline, Bridge may have lost its connection. The health check system will automatically attempt to reconnect within 60 seconds. If printers remain disconnected:
- Check your network connection
- Restart Bridge (close and reopen the app, or restart the Docker container)
- Verify the printers are still powered on and connected to WiFi
Printer-Specific Issues
Bambu Lab: "Connection refused" or "Auth failed"
- Access Code changed? Bambu resets the LAN Access Code after firmware updates. Check the printer touchscreen: Settings > WiFi > LAN Access Code.
- Serial number correct? Make sure you entered the full serial number (it's case-sensitive).
- LAN mode disabled? Some Bambu firmware versions require LAN mode to be explicitly enabled.
FlashForge: Can't find the Check Code
The Check Code is labeled "Printer ID" on the FlashForge touchscreen. Go to Settings (gear icon) > Network tab (second tab). Look for "Printer ID" — that's the check code Bridge needs.
FlashForge: Temperatures not showing
Make sure Bridge is reading the correct temperature fields. If nozzle temperature shows 0 while the printer is heating, update to the latest version of Bridge which fixes the temperature field mapping.
OctoPrint: 401 Unauthorized
Make sure you're using the Global API Key from OctoPrint Settings > API, not a user API key or application key.
Klipper: Port 7125 refused
Moonraker may not be running, or it may be on a different port. Check:
sudo systemctl status moonrakerAnd verify the port in your moonraker.conf:
[server]
port: 7125Anycubic: Can't connect
Anycubic Kobra 3 / V2 printers require Rinkhals to be installed first. Without Rinkhals, there's no local API for Bridge to connect to. See the Anycubic setup guide.
Elegoo: Shows "Unknown 0%" during print
Print info (filename, progress, layers) only appears once the printer transitions from preparing to actively printing. During heating, calibration, and bed leveling, the status may show as unknown with 0% progress. Once the first layer starts, all print data will populate.
Print Tracking Issues
Print shows 100% immediately after starting
This can happen if a previous print's telemetry data is cached. Bridge includes a guard against this — it ignores progress readings of 95% or higher within the first 2 minutes of a new print. If you're seeing this, update to the latest version of Bridge.
Print not tracking / not syncing to dashboard
Make sure your printer is linked to the dashboard with a Printer Code (phq_printer_...). Without linking, Bridge monitors the printer locally but doesn't sync to the cloud.
Docker Issues
Printer discovery not working in Docker
On Linux, --network host gives the container direct LAN access and discovery should work. On macOS and Windows, Docker Desktop runs containers in a VM, which breaks network broadcast protocols (mDNS, SSDP, UDP). Use the native desktop app instead of Docker on macOS/Windows.
Container keeps restarting
Check the container logs for errors:
docker logs printhq-bridgeCommon causes: port 9876 already in use, corrupted config file. Try removing the data volume and starting fresh:
docker rm -f printhq-bridge
docker volume rm bridge-dataPort Reference
| Platform | Default Port | Protocol |
|---|---|---|
| Bambu Lab | 8883 | MQTT/TLS |
| Creality | 9999 | HTTP/WS |
| FlashForge | 8898 / 8899 | HTTP / TCP |
| FlashForge Camera | 8080 | HTTP MJPEG |
| Elegoo | 3030 | WebSocket |
| Elegoo Camera | 3031 | HTTP |
| OctoPrint | 80 | HTTP |
| Klipper/Moonraker | 7125 | HTTP/WS |
| Bridge Web UI | 9876 | HTTP |
Log Locations
| Platform | Log Path |
|---|---|
| Desktop App | Check the Bridge web UI event log per printer |
| macOS (CLI) | ~/Library/Logs/printhq-bridge.log |
| Linux (CLI) | journalctl --user -u printhq-bridge |
| Windows (CLI) | %APPDATA%\printhq-bridge\bridge.log |
| Docker | docker logs printhq-bridge |
Still Need Help?
Join the PrintHQ Discord and ask in the support channel. Include:
- Your printer model and firmware version
- Your operating system
- Bridge version (shown in the web UI header)
- The error message or log output
- Steps you've already tried