Skip to main content

POS Hardware Troubleshooting

Common issues, connectivity problems, and driver troubleshooting for POS hardware.

Error Codes​

CodeDescriptionResolution
DEVICE_NOT_FOUNDDevice not connectedCheck connection
PRINTER_OFFLINEPrinter not respondingPower cycle, check network
PAPER_OUTPrinter out of paperReload paper
DRAWER_OPENCash drawer stuck openCheck for obstruction
READER_BUSYCard reader in useWait or cancel
CONNECTION_TIMEOUTDevice communication timeoutCheck network/cable

Printer Issues​

Printer Not Found​

Symptoms: Device discovery does not detect the printer.

Steps:

  1. Verify the printer is powered on and the indicator light is active
  2. For Ethernet printers, confirm the IP address matches configuration and is reachable (ping 192.168.1.100)
  3. For USB printers, check the cable connection and try a different USB port
  4. For Bluetooth printers, ensure pairing is complete and the device is within range
  5. Restart the printer and retry discovery

Printer Offline​

Symptoms: Printer was previously working but no longer responds.

Steps:

  1. Check the printer status indicator lights for errors (paper, cover, connection)
  2. Power cycle the printer (off for 10 seconds, then on)
  3. For network printers, verify the network switch and cables
  4. Check if the printer IP has changed (DHCP lease expiry)
  5. Run device health check from the Hardware Integration Hub

Paper Jam / Paper Out​

Symptoms: PAPER_OUT error or print jobs stuck in queue.

Steps:

  1. Open the printer cover and check for jammed paper
  2. Remove any torn paper fragments
  3. Load a fresh roll of thermal paper (ensure correct orientation -- print side facing out)
  4. Close the cover firmly until it clicks
  5. The printer should auto-feed and resume

Card Reader Issues​

Reader Not Connecting​

Steps:

  1. Check that the reader is charged (for battery-powered models)
  2. Ensure the reader firmware is up to date
  3. For Stripe Terminal, verify the location_id matches your Stripe account
  4. Restart the reader and retry connection
  5. Check Stripe Dashboard for reader status

Payment Timeout​

Steps:

  1. Check internet connectivity from the POS device
  2. Verify the Stripe API key is valid and not expired
  3. Cancel the current collect and retry
  4. If persistent, switch to offline payment mode (if available)

Cash Drawer Issues​

Drawer Won't Open​

Steps:

  1. For printer-driven drawers, verify the RJ12 cable between printer and drawer
  2. Check that the correct drawer pin is configured (pin 2 or pin 5)
  3. Test by sending an open command directly to the printer
  4. For USB drawers, check the USB connection and driver installation
  5. Manually release using the key lock as a last resort

Drawer Stuck Open​

Steps:

  1. Check for physical obstructions (coins, bills, debris)
  2. Gently push the drawer closed
  3. If the drawer sensor is malfunctioning, replace the micro-switch
  4. Verify the close detection works via status check API

Network Issues​

All Devices Offline​

Steps:

  1. Check the network switch powering the hardware subnet
  2. Verify the POS device itself has network connectivity
  3. Check for IP address conflicts on the hardware network
  4. Restart the network switch if all devices lost connection simultaneously
  5. Verify VLAN configuration if using segmented networks

Intermittent Connectivity​

Steps:

  1. Check for network congestion or bandwidth issues
  2. Verify cable quality (replace suspected bad cables)
  3. Check for wireless interference (for Bluetooth/Wi-Fi devices)
  4. Monitor device health logs for pattern recognition
  5. Consider upgrading to dedicated hardware network VLAN