Skip to content

Troubleshooting

Solutions for common issues with Bambuddy.

Printer Connection Issues

Printer Won't Connect

Symptoms: Printer shows as disconnected, red indicator

Solutions:

  1. Verify Developer Mode is enabled
  2. Check printer: Settings > Network > LAN Only Mode (must be ON)
  3. Then enable Developer Mode (appears after LAN Only Mode)

  4. Toggle off and on to get a fresh access code

  5. Check IP address

  6. Verify IP in printer network settings

  7. Ensure IP hasn't changed (use static IP or DHCP reservation)

  8. Verify access code

  9. Access code changes when Developer Mode is toggled

  10. Copy the code exactly (case-sensitive)

  11. Check network connectivity 

    ping YOUR_PRINTER_IP

  12. Verify ports are accessible

  13. MQTT: Port 8883
  14. FTPS: Port 990
telnet YOUR_PRINTER_IP 8883
  1. Check firewall rules
  2. Ensure Bambuddy server can reach printer
  3. Check both server and network firewalls

Connection Drops Frequently

Symptoms: Printer connects but disconnects intermittently

Solutions:

  1. Check WiFi signal strength
  2. View signal strength on printer card

  3. Move printer closer to router if weak

  4. Network congestion

  5. Too many devices on network

  6. Try a dedicated network/VLAN

  7. Router issues

  8. Restart router
  9. Check for firmware updates

  10. Disable "smart" features that may interfere

  11. Check Bambuddy logs 

    tail -f logs/bambuddy.log

  12. Enable FTP retry

  13. Go to Settings > General > FTP Retry
  14. Enable retry with 3 attempts and 2 second delay
  15. Increase connection timeout (default 30s) for slow WiFi
  16. Helps with intermittent connection issues during file transfers

A1/A1 Mini FTP Issues

Symptoms: File transfers fail with "read operation timed out" on A1 or A1 Mini printers

Background:

A1 and A1 Mini printers have different FTP/SSL behavior than X1C/P1S printers. They have issues with SSL encryption on the FTP data channel, causing transfers to hang or timeout waiting for completion responses. Bambuddy v0.1.6+ automatically detects A1/A1 Mini printers and skips SSL on the data channel while keeping the control channel encrypted via implicit FTPS.

Solutions:

  1. Update to latest Bambuddy version
  2. Version 0.1.6+ automatically handles A1 SSL compatibility

  3. No manual configuration required

  4. Increase FTP timeout for weak WiFi

  5. Go to Settings > General > FTP Retry
  6. Increase connection timeout from default 30s to 60-120s

  7. A1 printers often have weaker WiFi signal than X1C/P1S

  8. Improve WiFi signal

  9. A1 printers are known to have weak WiFi reception
  10. Check signal strength on printer card (-30 to -50 dBm = excellent, -50 to -70 dBm = fair, below -70 dBm = weak)

  11. Move printer closer to router or add a WiFi extender

  12. Enable FTP retry

  13. Go to Settings > General > FTP Retry
  14. Enable retry with 3-5 attempts and 2-3 second delay
  15. Combined with longer timeout, helps recover from transient failures

Wrong Printer Status

Symptoms: Status shows idle when printing, or vice versa

Solutions:

  1. Wait for sync
  2. Status updates every few seconds

  3. Refresh the page

  4. Check MQTT debug

  5. Enable MQTT debug logging

  6. Verify messages are being received

  7. Restart connection

  8. Delete printer from Bambuddy
  9. Re-add with correct details

SD Card Issues

Prints Won't Start / File Transfer Fails

Symptoms: Cannot start prints from Bambuddy, file transfers fail, or "No SD card" errors

Solutions:

  1. Ensure SD card is inserted
  2. An SD card is required for Bambuddy to work with your printer
  3. Check that the SD card is properly inserted in your printer

  4. The printer should recognize the SD card in its file browser

  5. Check SD card health

  6. Try a different SD card if transfers fail frequently
  7. Format the SD card using the printer's built-in format function

  8. Use a high-quality SD card (Class 10 or better recommended)

  9. SD card full

  10. Check available space on the SD card
  11. Delete old files from the printer's storage
  12. Use Bambuddy's File Manager to clean up files

SD Card Required

Bambuddy requires an SD card in your printer for:

  • Starting prints from Bambuddy or the print queue
  • Transferring files to/from the printer
  • Archiving completed prints (downloading 3MF files)
  • Firmware updates for LAN-only printers

Archiving Issues

Prints Not Being Archived

Symptoms: Prints complete but don't appear in archives

Solutions:

  1. Check SD card is inserted
  2. An SD card is required for archiving to work

  3. Verify the SD card is properly inserted and recognized

  4. Check printer connection

  5. Must be connected during and after print

  6. Verify green connection indicator

  7. Check FTP access

  8. Port 990 must be accessible

  9. Try downloading a file manually

  10. Check disk space

  11. Ensure enough space for 3MF files

  12. Clear old files if needed

  13. Enable FTP retry for weak WiFi

  14. P1S, X1C, A1, and other printers often have weak WiFi
  15. Go to Settings > General > FTP Retry
  16. Enable retry with 3-5 attempts and 2-3 second delay
  17. Increase connection timeout to 60-120s for A1/A1 Mini

  18. This helps when FTP transfers fail intermittently

  19. Check logs for errors 

    grep -i "archive\|error" logs/bambuddy.log

Wrong Timelapse Attached to Archive

Symptoms: After a print, the archive shows a timelapse from a previous print

Background:

In LAN-only mode (no cloud connection), Bambu printers don't sync their clock via NTP, so file modification times are unreliable. Bambuddy v0.1.9b+ uses a snapshot-diff approach instead of relying on mtime: it records which timelapse files exist before the print completes, then detects the new file that appears after encoding. If no new file is detected after retries, it falls back to matching the print name against filenames.

Solutions:

  1. Update to latest Bambuddy version
  2. Version 0.1.9b+ fixes the timelapse detection logic

  3. No manual configuration required

  4. Manual scan if auto-detection missed

  5. Open the archive
  6. Click Scan for Timelapse button

  7. This uses print-name matching and timestamp proximity

  8. Check printer storage

  9. Ensure the SD card has enough free space
  10. Old timelapse files may fill up the timelapse directory

Calibration Prints Being Archived

Symptoms: Calibration prints (flow rate, vibration compensation, bed leveling) appear in archives

Background:

Bambu printers run calibration routines using internal gcode files stored under /usr/ on the printer (e.g., /usr/etc/print/auto_cali_for_user.gcode). Bambuddy v0.1.9b+ automatically detects these internal files and skips archiving them.

Solutions:

  1. Update to latest Bambuddy version

  2. Version 0.1.9b+ automatically filters calibration prints

  3. Delete unwanted calibration archives

  4. Search for "auto_cali" in the archives search bar
  5. Select and delete any unwanted calibration archives

Duplicate Archives

Symptoms: Same print appears multiple times

Solutions:

  1. Enable duplicate detection
  2. Go to Settings > General

  3. Enable duplicate detection

  4. Clean up duplicates

  5. Filter archives by name
  6. Delete unwanted duplicates

Missing Thumbnails

Symptoms: Archive cards show placeholder instead of thumbnail

Solutions:

  1. Check 3MF file
  2. Some files don't include thumbnails

  3. Re-slice with thumbnail enabled

  4. Regenerate thumbnails

  5. Bambuddy can regenerate from 3MF
  6. Check Settings > Maintenance

Camera Issues

Camera Won't Stream

Symptoms: Camera page shows error or black screen

Solutions:

  1. Check ffmpeg installation 
    ffmpeg -version

Install if missing: 

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

  1. Verify camera is enabled
  2. Check printer settings

  3. Camera must be enabled in printer settings

  4. Check connection

  5. Camera requires active printer connection

  6. Verify printer shows as connected

  7. Try snapshot mode

  8. Click "Snapshot" instead of "Live"
  9. May work when streaming doesn't

Stream Freezes

Symptoms: Video starts but freezes

Solutions:

  1. Network bandwidth
  2. Lower FPS setting

  3. Check network congestion

  4. Check ffmpeg processes 

    ps aux | grep ffmpeg

Kill orphaned processes: 

killall ffmpeg

  1. Refresh the stream
  2. Click refresh button
  3. Close and reopen camera page

Notification Issues

Notifications Not Sending

Symptoms: No notifications received

Solutions:

  1. Test the provider
  2. Go to Settings > Notifications
  3. Click "Send Test"

  4. Check for errors

  5. Verify configuration

  6. Double-check API keys/tokens

  7. Verify phone numbers include country code

  8. Check quiet hours

  9. Notifications suppressed during quiet hours

  10. Verify current time vs quiet hours setting

  11. Check event triggers

  12. Ensure desired events are enabled
  13. Check printer filter settings

Notification Variables Empty

Symptoms: Messages show "Unknown" or blank for variables

Solutions:

  1. Update to latest version

  2. Variable handling improved in recent versions

  3. Check print data

  4. Some variables require specific print data
  5. May show "Unknown" for incomplete prints

Database Issues

Database Errors

Symptoms: 500 errors, data not saving

Solutions:

  1. Check disk space 

    df -h

  2. Verify database integrity 

    sqlite3 bambuddy.db "PRAGMA integrity_check;"

  3. Restore from backup

  4. If corrupted, restore from backup
  5. See Backup & Restore guide

"Database is locked" Errors

Symptoms: Intermittent "database is locked" errors, especially with multiple printers

Background:

Bambuddy v0.2.0b+ uses SQLite WAL (Write-Ahead Logging) mode, which significantly reduces lock contention by allowing simultaneous reads during writes. WAL mode is automatically enabled on startup along with a 5-second busy timeout.

Solutions:

  1. Update to latest Bambuddy version

  2. WAL mode is automatically enabled on startup — no configuration needed

  3. Check for WAL files

  4. SQLite WAL mode creates bambuddy.db-wal and bambuddy.db-shm files next to the database
  5. These are normal runtime files and should not be deleted while Bambuddy is running

  6. They are cleaned up automatically when the database is closed properly

  7. Docker volume mounts

  8. Ensure the data directory volume has sufficient write permissions
  9. WAL files must be on the same filesystem as the database

Search Not Working

Symptoms: Search returns no results or wrong results

Solutions:

  1. Rebuild FTS index
  2. Go to Settings > System Info

  3. Click "Rebuild Search Index"

  4. Check search syntax

  5. Use quotes for exact phrases
  6. Check for typos

Smart Plug Issues

Plug Not Responding

Symptoms: Can't control smart plug

Solutions:

  1. Verify IP address
  2. Check plug still has same IP

  3. Use static IP or DHCP reservation

  4. Test Tasmota interface

  5. Open http://PLUG_IP in browser

  6. Verify Tasmota web interface loads

  7. Check network access 

    curl "http://PLUG_IP/cm?cmnd=Status%200"

Auto Power-Off Not Working

Symptoms: Printer doesn't turn off after print

Solutions:

  1. Check feature is enabled

  2. Settings > Smart Plugs > Auto Power Off

  3. Verify cooldown settings

  4. Check temperature threshold

  5. Check cooldown time

  6. Check for queued prints

  7. Won't power off if more prints queued

General Issues

Bambuddy Won't Start

Solutions:

  1. Check Python version 

    python3 --version  # Need 3.10+

  2. Check dependencies 

    pip install -r requirements.txt

  3. Check port availability 

    lsof -i :8000

  4. Check logs 

    cat logs/bambuddy.log

Slow Performance

Solutions:

  1. Check system resources 

    htop

  2. Vacuum database

  3. Settings > System Info > Vacuum Database

  4. Clear old logs

  5. Logs rotate automatically

  6. Delete very old log files if needed

  7. Check for runaway processes 

    ps aux | grep -E "ffmpeg|python"

Getting More Help

Information to Gather

When reporting issues, include:

  1. Bambuddy version - Settings > About
  2. Printer model - X1C, P1S, etc.
  3. Operating system - Linux, macOS, Windows
  4. Installation method - Docker, manual
  5. Steps to reproduce - What you did
  6. Error messages - Exact text
  7. Logs - Relevant log entries

Where to Get Help

Debugging Mode

Enable debug logging for more details:

# In .env file
DEBUG=true

# Or environment variable
DEBUG=true uvicorn backend.app.main:app --host 0.0.0.0 --port 8000