FAQ & Troubleshooting

Find answers to frequently asked questions and learn how to resolve common configuration issues with the WooCommerce Print Barcode Labels plugin.

1. Print Server & Connection Issues

Why does the browser console show a WebSocket connection error?

  • Cause 1: Secure Websocket Block: Modern browsers block unsecured connections between an HTTPS WooCommerce site and local HTTP addresses.
    • Solution: Ensure your local print server is running on secure WebSockets (wss://). Follow the certificate guide in Print Server Setup.
  • Cause 2: Server Not Running: The local Node server is not started on the cashier computer.
    • Solution: Navigate to the server folder and run npm start in your command line. Keep the terminal window active.
  • Cause 3: Port Conflict: Another service is using port 8080.
    • Solution: Change the port number in the print server configuration and WooCommerce settings to an open port (e.g., 8081).

2. Printer & Output Issues

Why is my printer outputting raw ZPL code text instead of barcode labels?

  • Cause: The printer driver is not configured to accept raw printing commands, or the printer does not natively support Zebra Programming Language (ZPL).
    • Solution:
      • If using a Zebra printer, ensure the driver is set to Generic / Text Only or Pass-Through Mode so it does not interpret ZPL as document text.
      • If using non-ZPL printers (e.g. Dymo, Brother, or document printers), navigate to WooCommerce > Barcode Settings and switch the print mode from ZPL Commands to Image Canvas.

The barcode prints, but it is blurry and standard hardware scanners cannot read it.

  • Cause 1: Image Compression: Image/Canvas mode renders pixels. If the label is scaled down, the barcode bars blur.
    • Solution: Switch to ZPL Commands mode. ZPL uses vector graphics, rendering crisp bars at the printer's native DPI (e.g. 203 DPI or 300 DPI).
  • Cause 2: Label Density: The barcode is too small or complex (e.g., a long alphanumeric string on a small CODE39 barcode).
    • Solution: In the label editor, increase the height of the barcode component or switch the symbology to CODE128, which is much more compact than CODE39.

3. Scanner Issues

Why does the barcode scan, but no product is found?

  • Cause 1: Missing metadata: The barcode scanner has successfully read the barcode value, but the barcode value is not entered in the product's settings.
    • Solution: Edit the product in WooCommerce and verify that the exact scanned value matches the value in the Barcode Value input field.
  • Cause 2: Scanner Prefix/Suffix: Some scanners append a carriage return (Enter) or tab character, which can submit a search form prematurely before the entire barcode is loaded.
    • Solution: Refer to your barcode scanner's hardware manual to disable automatic prefix/suffix carriage returns.

[!CAUTION] Data Backup: When assigning barcode values in bulk using database imports, always backup your database first. The plugin uses WordPress postmeta tables, and database corruptions can wipe out custom inventory UPC/EAN mappings.