Printer troubleshooting

Thermal printers are simple, but a few things reliably go wrong: a changed network address, a loose cable, or a task with no slip to print through. Find your symptom below. For setup, see Setting up a printer.

Start here#

1. Settings → Printer — confirm Enable printing is on.
2. Press the status dot (Check status). Green = reachable, red = not.
3. Press Test — it should print "Test Print Successful!" If the test works but a task doesn't, jump to A task won't print.

The status is green but nothing prints#

The status check only confirms Todebaran can reach the printer — not that it's truly ready. A green light with no paper coming out almost always means:

• Out of paper, or the roll is in backwards (thermal paper only prints on one side — if the test is blank, flip the roll).
• The cover is open or not latched.
• The printer is in an error state — check its own status light and power‑cycle it.

It can't reach the printer#

If the status stays red, match your connection type.

Network printers#

Common messages: "Failed to connect to printer.", "Printer IP address or port not set.", or "Printer connection unexpectedly closed."

• Confirm the IP address and port (usually 9100) are correct.
• Make sure the Mac and printer are on the same network — not a guest Wi‑Fi or a separate VLAN.
• The IP may have changed since you set it up. Print the printer's self‑test to see its current address, and set a DHCP reservation so it stops moving — see Setting up a network printer.
• Try Detect to find it via Bonjour; if that finds nothing, enter the IP by hand.

USB printers#

Common message: "USB printer not found. Please check connection or Vendor/Product ID."

• Check the cable and that the printer is powered on.
• Press Detect to list connected USB printers and pick yours — it fills in the Vendor and Product IDs correctly.
• If a print hangs, you may see "USB print transfer timed out after 30 seconds." — usually a paper jam or the printer lost power mid‑job. Clear it and retry.

Serial printers#

Common messages: "Serial printer port path was not provided and could not be discovered." or "Serial port closed unexpectedly."

• Check the port path and baud rate (9600 is typical).
• Press Detect to list available ports.
• For a Bluetooth‑serial printer, make sure it's paired in System Settings first, then use its /dev/… path.

A task won't print#

Printing a task needs a slip to lay it out:

• "No default task slip set. Mark a slip as the default for tasks." — the task has no slip attached and you haven't set a default. Build a slip and toggle Set as default for tasks in the slip editor.
• "Matching slip template not found." — the task points at a slip that was deleted. Attach a different slip, or set a default.

Printing stopped partway through#

Jobs print one item at a time, and printing stops at the first failure so you don't waste a roll. The remaining items stay queued and the button becomes Retry — fix the cause (usually paper or connection) and press Retry to resume just the failed items.

The layout looks wrong#

• Too narrow, or text runs off the edge — the printer Model doesn't match your paper. An 80 mm printer set to a 58 mm model (or vice‑versa) mislays every line. Pick the right model — see Compatible printers.
• It won't cut — a few basic 58 mm models have no cutter and just feed the paper to tear off. Otherwise, check that your slip doesn't end on an extra manual Cut block.
• Blank or nearly empty — empty blocks are skipped on purpose so they don't waste paper; a slip with nothing resolved prints just a cut.

Images or QR codes look wrong#

• A box like [Image: …] or [Image from URL] means the image couldn't be loaded — a missing file, or a URL that didn't respond (image downloads time out after 10 seconds).
• [Image loading error: …] (including "Image is too small to print.") means the image couldn't be processed or was too small once fitted to the paper.
• Thermal printers are 1‑bit — photos are dithered to black and white, so fine detail and light colors may drop out. Prefer high‑contrast images and bold QR codes.

Detect finds nothing#

• "No Network printers found." / "No USB printers found." / "No Serial printers found." — nothing was discovered. Confirm the printer is on and connected, then enter its details manually (network printers must support Bonjour to be auto‑detected).
• "Error detecting printers." — detection itself failed; restart the app and try again.

Still stuck?#

• Power‑cycle the printer and press Check status again.
• Delete and re‑add the printer to start its configuration fresh.
• If it persists, contact support with your printer's make, model and connection type.