Troubleshooting

This guide covers common problems and their solutions.

Connection Issues

“Printer not responding” (Network)

Symptoms:

  • PrinterTimeoutError exception

  • No response from printer

Solutions:

  1. Verify printer is powered on and connected to network

    ping 192.168.1.100

  2. Check IP address is correct

    • Print network configuration from printer menu

    • Verify IP hasn’t changed (use static IP or DHCP reservation)

  3. Check firewall settings

    # Linux: Allow port 9100
sudo ufw allow 9100/tcp

# Test with telnet
telnet 192.168.1.100 9100

  4. Try different network

    • Some networks block printer protocols

    • Corporate networks may require special configuration

  5. Increase timeout

    connection = ConnectionNetwork("192.168.1.100")
printer = PTP900(connection)

# After first connection, adjust timeout
printer.print(first_label)
if hasattr(connection, '_socket'):
     connection._socket.settimeout(30.0)

“Permission denied” (USB)

Symptoms:

  • PrinterPermissionError exception

  • usb.core.USBError: [Errno 13] Access denied (insufficient permissions)

Solutions:

  1. Configure USB permissions (recommended)

    See Installation for detailed udev rules setup.

  2. Run with sudo (not recommended)

    sudo python your_script.py

“Printer not found” (USB)

Symptoms:

  • PrinterNotFoundError exception

  • No USB device found

Solutions:

  1. Verify USB connection

    lsusb | grep Brother
# Should show: Bus 001 Device 010: ID 04f9:20af Brother Industries, Ltd

  2. Check product ID matches

    import usb.core

# List all Brother devices
devices = usb.core.find(find_all=True, idVendor=0x04f9)
for dev in devices:
    print(f"Product ID: {hex(dev.idProduct)}")

# Compare with printer class USB_PRODUCT_ID

  3. Try different USB port

    • Some USB hubs cause issues

    • Try direct connection to computer

  4. Check USB cable

    • Try a different cable

    • Some cables are power-only

Network Error After Print Start

Symptoms:

  • Print starts but fails mid-job

  • PrinterNetworkError during printing

Solutions:

  1. Check WiFi signal strength

    • Move printer closer to access point

    • Use Ethernet instead of WiFi

  2. Implement retry logic

    def print_with_retry(printer, label, max_retries=3):
    for attempt in range(max_retries):
        try:
            printer.print(label)
            return
        except PrinterNetworkError:
            if attempt == max_retries - 1:
                raise
            print(f"Retry {attempt + 1}/{max_retries}...")
            time.sleep(2)

Software Issues

Import Errors

Symptoms:

  • ModuleNotFoundError: No module named 'ptouch'

  • ImportError: cannot import name 'PTP900'

Solutions:

  1. Verify installation

    pip list | grep ptouch
# Should show: ptouch  1.0.0 (or similar)

  2. Reinstall package

    pip uninstall ptouch
pip install ptouch

  3. Check Python version

    python --version
# Requires Python 3.11 or later

  4. Virtual environment issues

    # Ensure you're in the correct venv
which python
pip install ptouch

Font Errors

Symptoms:

  • OSError: cannot open resource

  • AttributeError: 'NoneType' object has no attribute 'getsize'

Solutions:

  1. Use ImageFont.load_default()

    from PIL import ImageFont

# Simplest solution - always available
font = ImageFont.load_default()

  2. Verify font file path

    import os

font_path = "/path/to/font.ttf"
if not os.path.exists(font_path):
    print(f"Font not found: {font_path}")

# Use absolute paths
font = ImageFont.truetype(os.path.abspath(font_path), 48)

  3. Find system fonts

    # Linux
fc-list : file | grep -i dejavu

# macOS
ls /System/Library/Fonts/
ls ~/Library/Fonts/

# Windows
dir C:\\Windows\\Fonts

  4. Install fonts

    # Debian/Ubuntu
sudo apt install fonts-dejavu

# Fedora/RHEL
sudo dnf install dejavu-fonts

Command Line Issues

“ptouch: command not found”

Solutions:

  1. Use python -m

    python -m ptouch "Hello World" --host 192.168.1.100 \
    --printer P900 --tape-width 36

  2. Check installation

    pip show ptouch
# Look for "Location" line

# Check if scripts directory is in PATH
echo $PATH

  3. Reinstall with –force-reinstall

    pip install --force-reinstall ptouch

Wrong Arguments Error

Symptoms:

  • error: the following arguments are required

Solutions:

  1. Check required arguments

    ptouch --help

# Required: --host or --usb, --printer, --tape-width
# Required: text or --image

  2. Common mistakes

    # Wrong: Missing connection
ptouch "Text" --printer P900 --tape-width 36

# Correct:
ptouch "Text" --host 192.168.1.100 --printer P900 --tape-width 36

# Wrong: Missing text
ptouch --host 192.168.1.100 --printer P900 --tape-width 36

# Correct:
ptouch "Hello" --host 192.168.1.100 --printer P900 --tape-width 36

Performance Issues

Slow Printing

Causes and Solutions:

  1. High resolution mode enabled

    • High-res doubles print time

    • Use standard resolution if quality permits

    printer = PTP900(connection, high_resolution=False)

  2. Large images

    • Resize images to required dimensions

    • Don’t use images larger than necessary

  3. Network latency

    • Use USB instead of network if possible

    • Check network connection quality

  4. Compression disabled

    • Enable compression (it’s on by default)

    printer.print(label, use_compression=True)

  5. Individual prints instead of batch

    # Slow: Individual prints
for text in texts:
    label = TextLabel(text, Tape12mm, font=font)
    printer.print(label)

# Fast: Batch printing
labels = [TextLabel(t, Tape12mm, font=font) for t in texts]
printer.print_multi(labels)

Getting More Help

If you can’t solve your issue:

  1. Check GitHub Issues

  2. Enable Debug Logging

    import logging

logging.basicConfig(level=logging.DEBUG)
# Now run your code - more verbose output

  3. Create Minimal Example

    • Simplify your code to smallest example that reproduces the issue

    • Remove unrelated code

    • Use simple test data

  4. File a Bug Report

    Include:

    • Python version: python --version

    • Package version: pip show ptouch

    • Operating system

    • Printer model

    • Minimal code example

    • Complete error message with stack trace

    • What you’ve already tried

    Create issue at: https://github.com/nbuchwitz/ptouch/issues/new

  5. Check Documentation