Troubleshooting

Open Print Settings First

Most printing issues are easier to diagnose from the Print Settings overlay than from the Print dialog itself.

Open Print Settings from the application menu, from the Command Menu, or from the gear button in the Print dialog.

The left side of the overlay is split into:

  • Mode: choose the active print path.
  • System Print: browser or operating-system printing.
  • USB: direct receipt-printer configuration.
  • Bluetooth: Bluetooth receipt-printer connection and output.
  • Mac Alternative: image printing through the system printer queue.
  • MQTT: broker-based remote printing.

If a print job fails, first confirm that the selected mode in Mode matches the panel you actually configured.

USB Receipt Printer

I can’t find my exact printer model

Choose the closest supported model from the same brand, or use a generic model if needed. The model mainly affects command compatibility.

Some characters do not print correctly

Open Print Settings > USB and switch Print Type to Image. Image mode supports more characters and mixed-language content than direct command printing.

Printing is slow

If your printer already handles your language and characters correctly, use Print Type > Direct in Print Settings > USB. Direct mode is faster than image mode.

The preview or printed content is cut off

When using image mode, review the image settings below the USB configuration:

  • DPI
  • Width (mm)
  • Left / Right / Top / Bottom padding

If the receipt is still clipped, reduce the width slightly or increase the hardware margins with padding.

The bottom of the ticket is too close to the cut

Open Print Settings > USB, enable Advanced Options, then increase Feed Before Cut.

I get extra blank lines or broken line breaks

Open Print Settings > USB, enable Advanced Options, then try another Newline Character value.

Images do not print correctly in direct mode

Open Print Settings > USB, enable Advanced Options, then switch Image Mode between Column and Raster.

Font sizes are too large in direct mode

That is expected. In Direct mode, layout is mostly controlled by the printer language and firmware. If you need precise visual control over font sizes and spacing, use Image mode instead.

Bluetooth Receipt Printer

No Bluetooth printer appears when scanning

Open Print Settings > Bluetooth and scan again with the printer powered on and in pairing mode.

On macOS, also check System Settings > Privacy & Security > Bluetooth and confirm Colonnes has permission to use Bluetooth.

The printer was found but will not connect

Retry the connection from Print Settings > Bluetooth. If the printer still refuses the connection, disconnect it from other devices first, then scan again.

Bluetooth printing works but some characters are wrong

Switch Print Type to Image in Print Settings > Bluetooth. If you stay in direct mode, review the selected printer model and advanced output settings.

Mac Alternative

My printer works in macOS but not in USB receipt-printer mode

Use Print Settings > Mode and select Receipt Printer (Mac Alternative). Then open the Mac Alternative panel and choose the printer installed in macOS.

This mode sends generated images through the system print queue instead of direct receipt-printer commands.

My Star Micronics printer does not print on recent macOS versions

Star Micronics printers often fail with direct ESC/POS-style printing on recent macOS versions. Use Receipt Printer (Mac Alternative) instead.

Open Print Settings > Mode, select Receipt Printer (Mac Alternative), then open the Mac Alternative panel to choose your printer and adjust the image settings.

The bottom padding is being trimmed

Open Print Settings > Mac Alternative and enable Prevent Trim. This adds a small guard line that helps some drivers keep the configured bottom margin.

MQTT

Nothing is received by my bridge or remote printer

Open Print Settings > MQTT and verify:

  • Broker URL
  • Topic
  • QoS
  • Username / Password, if your broker requires authentication

Also confirm that Mode is set to Receipt Printer (MQTT) before sending the print job.

The payload shape is wrong for my integration

Adjust the JSON Template in Print Settings > MQTT. Colonnes can inject values such as ${image_base64}, ${paper_width_mm}, ${paper_height_mm}, and ${timestamp}.

System Print

I just want to print to a normal office printer or PDF

Use Mode > System Print. Then configure any browser-style output options in the System Print panel and complete the final print step in the operating-system print dialog.

The output is too small or too large

Adjust Font Size in Print Settings > System Print. For black-and-white output, disable Color there as well.

Cross-Platform Compatibility

Which printer brand is the safest across macOS, Windows, and Linux?

Epson remains the safest choice for standard receipt-printer workflows across all major desktop platforms.

My printer works on Windows but not on macOS

This is common with some Star Micronics setups. Keep the direct receipt-printer workflow on Windows, and use Mac Alternative on macOS when direct printing fails.