Skip to content

Troubleshooting

Common issues and solutions for Printernizer. If you don't find your issue here, please open a GitHub issue.

Quick Diagnostics

Check System Health

curl http://localhost:8000/api/v1/health

Expected response: 

{
  "status": "healthy",
  "version": "2.7.0",
  "uptime": 3600,
  "database": "connected"
}

Check Logs

Python Standalone: 

# Logs are written to stdout
# Check terminal where Printernizer is running

Docker: 

docker-compose logs -f printernizer

Home Assistant: - Go to Add-on page → Printernizer → Log tab

Printer Connection Issues

Printer Won't Connect

Symptoms: Printer shows "Disconnected" or "Error" status

Solutions:

  1. Verify network connectivity: 

    ping <printer-ip-address>

  2. Check printer is powered on and connected to network

  3. Verify same network/subnet - Printer and Printernizer must be on same network

  4. For Bambu Lab:

  5. Enable "LAN Mode" in printer settings
  6. Verify access code is correct
  7. Check MQTT port 8883 is not blocked

  8. Try rebooting the printer

  9. For Prusa:

  10. Verify PrusaLink is running (check printer screen)
  11. Confirm API key is correct
  12. Check HTTP port (usually 80 or 8080)

  13. Access PrusaLink web interface to verify it's working

  14. Check firewall settings:

  15. Bambu Lab: Allow outbound MQTT (port 8883)

  16. Prusa: Allow outbound HTTP (port 80/8080)

  17. Restart Printernizer after fixing configuration

Auto-Discovery Not Working

Symptoms: No printers found during discovery scan

Solutions:

  1. Ensure printers are on and network-connected

  2. Check network settings:

  3. Disable VPN if active
  4. Ensure multicast is enabled on network

  5. Check router doesn't block mDNS/SSDP

  6. Try manual addition instead (works more reliably)

  7. For Bambu Lab:

  8. Verify SSDP discovery is enabled on router

  9. Check printer firmware is up to date

  10. For Prusa:

  11. Verify Bonjour/mDNS is working
  12. Check printer hostname resolves: ping prusa.local

Connection Drops Frequently

Symptoms: Printer connects then disconnects repeatedly

Solutions:

  1. Check network stability:
  2. Run continuous ping test
  3. Check for network congestion

  4. Verify WiFi signal strength (if printer is wireless)

  5. Increase retry intervals: 

    BAMBU_RETRY_INTERVAL=60
PRUSA_POLL_INTERVAL=10

  6. Check printer firmware:

  7. Update to latest version

  8. Check manufacturer known issues

  9. Reduce polling frequency if printer is slow to respond

Application Issues

Printernizer Won't Start

Symptoms: Application crashes on startup or won't start

Solutions:

  1. Check Python version: 

    python --version  # Should be 3.8+

  2. Verify dependencies installed: 

    pip install -r requirements.txt

  3. Check port availability: 

    # Linux/Mac
lsof -i :8000

# Windows
netstat -ano | findstr :8000

  4. Check database permissions: 

    # Ensure data/ directory is writable
chmod 755 data/

  5. Review logs for specific error messages

  6. Try clean start: 

    # Backup database
cp data/printernizer.db data/printernizer.db.bak

# Remove database (creates new one)
rm data/printernizer.db

# Start application
python src/main.py

Port Already in Use

Symptoms: Error "Address already in use" or similar

Solutions:

  1. Change port: 

    PORT=8001

  2. Kill existing process: 

    # Linux/Mac
lsof -ti:8000 | xargs kill -9

# Windows
netstat -ano | findstr :8000
# Note the PID, then:
taskkill /PID <pid> /F

  3. Check for orphaned processes: 

    ps aux | grep python

Web Interface Not Loading

Symptoms: Blank page, 404 errors, or connection refused

Solutions:

  1. Verify Printernizer is running: 

    curl http://localhost:8000/api/v1/health

  2. Check browser console for JavaScript errors (F12)

  3. Clear browser cache and reload

  4. Try different browser

  5. Check firewall:

  6. Allow port 8000 inbound

  7. Temporarily disable firewall to test

  8. Verify correct URL:

  9. http://localhost:8000 (not https)
  10. No trailing slash issues

Job Monitoring Issues

Jobs Not Appearing

Symptoms: Print jobs don't show up in Printernizer

Solutions:

  1. Verify printer connection (must be "Connected" status)

  2. Check job is actually running on the printer

  3. Refresh the page or restart WebSocket connection

  4. For Bambu Lab:

  5. Verify MQTT connection is stable
  6. Check printer is in LAN mode

  7. Try restarting printer

  8. For Prusa:

  9. Verify PrusaLink is reporting job status
  10. Check PrusaLink web interface shows job

  11. Verify API polling is working

  12. Check database: 

    sqlite3 data/printernizer.db "SELECT * FROM jobs LIMIT 10;"

Job Progress Not Updating

Symptoms: Job shows 0% or stale progress

Solutions:

  1. Check WebSocket connection:
  2. Open browser console (F12)
  3. Look for WebSocket connection messages

  4. Verify no errors

  5. Refresh the page

  6. Verify printer is sending updates:

  7. Check printer display shows progress

  8. For Prusa: Check PrusaLink shows progress

  9. Check polling interval (for Prusa): 

    PRUSA_POLL_INTERVAL=5  # Check every 5 seconds

File Management Issues

Files Not Showing

Symptoms: File browser is empty or incomplete

Solutions:

  1. Verify printer connection (must be connected)

  2. Check printer has files:

  3. For Bambu Lab: Check printer touchscreen

  4. For Prusa: Check PrusaLink file browser

  5. Refresh file list:

  6. Click refresh button

  7. Or reload page

  8. Check permissions:

  9. Verify API key/access code has file access

  10. Check logs for file listing errors

File Download Fails

Symptoms: Download starts but fails or gets stuck

Solutions:

  1. Check disk space: 

    df -h  # Linux/Mac

  2. Verify download path is writable: 

    chmod 755 ./downloads

  3. Check file exists on printer

  4. Try smaller file to test

  5. Check network stability:

  6. Large files may timeout on unstable connections

  7. Increase timeout: 

    DOWNLOAD_TIMEOUT=600  # 10 minutes

  8. Check logs for specific error

3D Preview Not Generating

Symptoms: File shows no preview thumbnail

Solutions:

  1. Check file format supported:
  2. Supported: STL, 3MF, GCODE, BGCODE

  3. Others: No preview available

  4. Verify preview generation enabled: 

    PREVIEW_ENABLED=true

  5. Check dependencies installed: 

    pip install trimesh numpy-stl matplotlib scipy

  6. File may be corrupted:

  7. Try downloading file manually

  8. Test with different file

  9. Check logs for generation errors

Database Issues

Database Locked

Symptoms: "Database is locked" errors

Solutions:

  1. Enable WAL mode: 

    DATABASE_WAL_MODE=true

  2. Close other connections:

  3. Stop other Printernizer instances

  4. Close database browser tools

  5. Check file permissions: 

    chmod 644 data/printernizer.db

  6. Increase timeout: 

    DATABASE_TIMEOUT=30

Database Corruption

Symptoms: "Database disk image is malformed" or similar

Solutions:

  1. Check database integrity: 

    sqlite3 data/printernizer.db "PRAGMA integrity_check;"

  2. Try to repair: 

    sqlite3 data/printernizer.db ".recover" | sqlite3 data/printernizer_recovered.db

  3. Restore from backup: 

    cp data/printernizer.db.bak data/printernizer.db

  4. If no backup, start fresh:

  5. Backup current: cp data/printernizer.db data/printernizer.db.old
  6. Remove: rm data/printernizer.db
  7. Restart Printernizer

Performance Issues

Slow Response Times

Symptoms: Web interface is slow or unresponsive

Solutions:

  1. Check system resources: 

    top  # Linux/Mac
# or
Task Manager  # Windows

  2. Reduce concurrent operations:

  3. Limit number of printers
  4. Reduce polling frequency

  5. Disable auto-download temporarily

  6. Increase worker processes: 

    WORKERS=4

  7. Use SSD for database:

  8. Move database to SSD storage

  9. Clear old job history: 

    DELETE FROM jobs WHERE created_at < datetime('now', '-90 days');

  10. Restart Printernizer

High Memory Usage

Symptoms: Memory usage constantly increasing

Solutions:

  1. Restart Printernizer (temporary fix)

  2. Check for memory leaks:

  3. Monitor memory over time

  4. Report issue with details

  5. Reduce cache sizes: 

    PREVIEW_CACHE_DAYS=7

  6. Limit concurrent downloads

Docker-Specific Issues

Container Won't Start

See Docker Deployment Guide for Docker-specific troubleshooting.

Volume Permission Issues

# Fix permission issues
sudo chown -R 1000:1000 ./data

Home Assistant Add-on Issues

Add-on Won't Install

  1. Check Home Assistant version (requires recent version)
  2. Verify repository URL is correct
  3. Check Home Assistant logs
  4. Try refreshing add-on store

Add-on Won't Start

  1. Check add-on logs
  2. Verify configuration is valid YAML
  3. Check for port conflicts
  4. Restart Home Assistant

Getting Help

If you still have issues:

  1. Check logs for detailed error messages
  2. Search existing issues: GitHub Issues
  3. Create new issue with:
  4. Printernizer version
  5. Deployment method
  6. Printer type
  7. Steps to reproduce
  8. Error logs
  9. Screenshots (if applicable)

Diagnostic Information

When reporting issues, include:

# System info
curl http://localhost:8000/api/v1/health

# Python version
python --version

# Printernizer version
cat src/main.py | grep "APP_VERSION"

# OS info
uname -a  # Linux/Mac
systeminfo  # Windows

Additional Resources