# Printer Troubleshooting
> Source: https://development.fuze-store.com/docs/app/printer/troubleshooting

# Printer Troubleshooting

This page is a quick-fix guide for the most common printer problems. Each section follows the same format: **Symptom → Likely cause → How to fix**.

If nothing here helps, contact Fuze Store support with the printer model, the connection type, and any error messages you see.

## My printer is not detected

### Bluetooth printer not appearing

**Symptom**: You tap **Add Printer → Bluetooth → Scan** and your printer doesn't show up.

**Likely cause**: The printer isn't in pairing mode, Bluetooth is off, or another device is already paired to the printer.

**How to fix**:

  
    Power-cycle the printer and put it back into pairing mode (usually a long
    press of the feed button — check the manual).
  
  
    Make sure Bluetooth is **on** in your phone or tablet settings, and that
    you've granted Bluetooth permission to the Fuze Store app.
  
  
    Forget any other Bluetooth pairings to this printer — most thermal printers
    only allow **one** active pairing at a time.
  
  Stay within ~10 meters of the printer while pairing.
  Tap **Scan** again.

### Network (TCP/IP) printer connection failed

**Symptom**: You enter the IP address and port but **Test Print** fails.

**Likely cause**: Wrong IP, wrong port, or the printer is on a different network.

**How to fix**:

  
    Print a network self-test page from the printer to confirm its **IP
    address**.
  
  
    Make sure your POS device and the printer are on the **same Wi-Fi
    network**. Some stores have separate "guest" and "staff" networks — both
    devices must be on the staff one.
  
  
    Confirm the port is **9100** (the thermal printer default) unless your
    printer's manual says otherwise.
  
  
    From a laptop on the same network, try opening
    `http://<printer-ip>:9100` in a browser. If nothing happens (which is
    expected), at least confirm the address can be reached. If the connection
    immediately fails, the printer or your network is the problem.
  

### USB printer not found by the LAN Bridge

**Symptom**: You select **USB** in Fuze Store, tap **Discover USB Printers**, and no printers appear.

**Likely cause**: The LAN Bridge is not running, the USB cable is loose, or the LAN Bridge can't access USB devices on its host computer.

**How to fix**:

  
    Make sure the **Discover USB Printers** button is active (not grayed
    out). If it's grayed out, your device is not connected to the Fuze
    Store Hub — open **Configurations → Integrations → Fuze Store Hub** and
    confirm the connection shows paired and green.
  
  
    Confirm Fuze Store Hub is running on the Hub computer. Open
    `https://<hub-ip>:18443/health` in a browser (accept the one-time
    self-signed certificate warning) — you should see `{ "status": "ok" }`.
  
  Reseat the USB cable, or try a different USB port on the Hub computer.
  
    On **Windows**: Fuze Store Hub will normally print through the Windows
    Print Spooler, so make sure your printer is installed with its
    manufacturer's driver and visible under **Settings → Bluetooth &
    devices → Printers & scanners**. You do not need to replace the driver.
  
  
    On **macOS**: if the printer shows up in **System Settings → Printers &
    Scanners**, remove it there. macOS claims the USB device through CUPS on
    plug-in and prevents Fuze Store Hub from talking to it directly.
  
  
    On **Linux**: USB printers need access permissions. Install the Fuze
    Store Hub udev rules (or run the Hub with elevated permissions for a
    quick test).
  
  Restart Fuze Store Hub after any of the above, then tap **Discover USB Printers** again in the app.

  If discovery still shows nothing, you can add the printer manually. Find
  the Vendor ID and Product ID from your printer's manual, Device Manager
  (Windows), or `lsusb` (Linux/macOS), and enter them as 4-character hex
  codes (e.g. `04b8`, `0202`).

  Fuze Store Hub exposes `GET /info` which shows exactly which USB path is
  available on its host (`libusb` vs `windowsSpooler`). Useful for diagnosis:
  `curl -k https://<hub-ip>:18443/info` (the `-k` skips the self-signed-cert check).

## My receipts are garbled or showing strange characters

**Symptom**: Receipts print with random symbols, square boxes, or question marks where letters should be.

**Likely cause**: The encoding is wrong for the language you're printing.

**How to fix**:

  Open the printer's edit page in **Store → Printers**.
  
    Change the **Encoding** field. Use:
    
    | Language | Encoding |
    |---|---|
    | English / Spanish / French / Latin scripts | `UTF-8` (default) |
    | Chinese | `GB18030` or `GBK` |
    | Japanese | `Shift_JIS` |
    | Korean | `EUC-KR` |
    | Older / US-only printers | `CP437` |
  
  Save and **Test Print** to verify.

## The wrong printer is printing my receipt

**Symptom**: Drinks are printing in the kitchen, or food orders are landing on the bar printer.

**Likely cause**: A routing rule is misconfigured — the filter is wrong, or a rule was created for the wrong printer.

**How to fix**:

  
    Open **Store → Printers**, then tap the printer that received the wrong
    receipt.
  
  Open its **Routing Rules** tab.
  
    Check each rule's **Function**, **Trigger Event**, and **Filter**. Are the
    categories correct? Is "All orders" toggled on when it shouldn't be?
  
  Edit or delete the rule, then test by ringing up a sample order.

For a guide on setting up routing rules properly, see [Routing Rules](/docs/app/printer/routing-rules).

## I'm getting duplicate prints

**Symptom**: Two copies of the same receipt or kitchen ticket appear when only one should.

**Likely cause**: Two routing rules overlap — for example, one rule says "Receipt on Payment Completed for all orders" and another says "Receipt on Payment Completed for In-Store orders". An in-store payment fires both.

**How to fix**:

  Open **Store → Printers** and review the rules on every printer.
  
    Look for two or more rules with the **same Function** and the **same
    Trigger Event** that could both match a single order.
  
  Delete or narrow one of the overlapping rules.
  Place a test order to confirm only one print fires.

  If you actually want two copies of the same receipt, set the **Copies** field
  on a single routing rule to 2 instead of creating a duplicate rule.

## Print queue is not draining

**Symptom**: The Status & Queue card on the printer detail page shows queued jobs that never go through, even after the printer is back online.

**Likely cause**: The LAN Bridge or the connection to it is still down, or the printer is offline at the hardware level.

**How to fix**:

  
    Check the **connection badge** at the top of the app. If it shows
    "LAN disconnected", the LAN Bridge is the problem — restart it and reload
    the app.
  
  
    Check the printer's hardware: power, paper, no paper jam, and that the
    cable or Wi-Fi is intact.
  
  
    Open the printer detail page and tap **Test Print**. If that fails, the
    queue won't drain either.
  
  
    Once the printer is healthy, tap **Retry** on each failed job — or wait
    5 seconds for Fuze Store to flush the queue automatically.
  

## The cutter isn't cutting the paper

**Symptom**: Receipts print but never cut — you have to tear them by hand.

**Likely cause**: Either the printer doesn't have a cutter, or the cutter capability is turned off in Fuze Store.

**How to fix**:

  Open the printer's edit page.
  
    Find the **Capabilities** section and make sure **Cutter** is toggled
    **on**.
  
  
    If your printer has a cutter and it still doesn't work, check the printer
    manual — some models need a specific firmware version or have a physical
    cutter switch.
  

## A toast says "Failover active"

**Symptom**: After a print, a toast appears that says **"Failover active — receipt printed on backup"**.

**Likely cause**: This is **not an error**. It means your primary printer for that function failed, and Fuze Store automatically printed on the next-priority backup printer instead.

**How to fix**: Check your primary printer when you have a moment. It probably ran out of paper, lost its connection, or had a paper jam. The receipt was already printed safely on the backup.

For more details, see [Routing Rules → Priority and failover](/docs/app/printer/routing-rules#priority-and-failover).

## Receipts are clipped or only half-filling the paper

**Symptom**: Receipts are missing the right side of the page, or they only fill the left half of the paper.

**Likely cause**: The **paper width** in Fuze Store doesn't match the actual physical paper width.

**How to fix**:

  Open the printer's edit page.
  
    Set **Paper Width** to either `58mm` or `80mm` to match what's loaded in
    the printer. Most receipt printers are 80mm; small portable printers are
    usually 58mm.
  
  Save and **Test Print** to confirm.

## Bluetooth permission denied on iPhone or Android

**Symptom**: You see **"Bluetooth permission required"** even after granting permission.

**Likely cause**: System permission was denied or revoked outside the app.

**How to fix**:

  
    On **iOS**: open Settings → Fuze Store → toggle **Bluetooth** on.
  
  
    On **Android**: open Settings → Apps → Fuze Store → Permissions → enable
    **Nearby devices** (or **Bluetooth**, depending on Android version).
  
  Force-quit and reopen the Fuze Store app.

## Getting more help

If none of the above fixes your issue:

1. Check the printer manufacturer's documentation. Most quirks are model-specific.
2. Confirm your printer supports **ESC/POS** commands — Fuze Store uses ESC/POS, the standard for thermal printers. If your printer needs a proprietary driver, it won't work.
3. Run a **Test Print** from the printer detail page and see what (if anything) the printer does.
4. Contact Fuze Store support with:
   - Your printer's brand and model
   - The connection type (Bluetooth / TCP / USB / Serial)
   - The exact error message or toast
   - The steps to reproduce the issue

## Related guides

- [Printers Overview](/docs/app/printer/overview)
- [Connecting a Printer](/docs/app/printer/connecting-a-printer)
- [Routing Rules](/docs/app/printer/routing-rules)
- [LAN Bridge Setup](/docs/app/printer/lan-bridge-setup)
- [Print Queue & Status](/docs/app/printer/print-queue-and-status)