Troubleshooting¶

Solutions for common issues with Bambuddy.

Printer Connection Issues¶

Printer Won't Connect¶

Symptoms: Printer shows as disconnected, red indicator

Solutions:

Verify Developer Mode is enabled
Check printer: Settings > Network > LAN Only Mode (must be ON)
Then enable Developer Mode (appears after LAN Only Mode)
Toggle off and on to get a fresh access code
Check IP address
Verify IP in printer network settings
Ensure IP hasn't changed (use static IP or DHCP reservation)
Verify access code
Access code changes when Developer Mode is toggled
Copy the code exactly (case-sensitive)
Check network connectivity
```
ping YOUR_PRINTER_IP
```
Verify ports are accessible
MQTT: Port 8883
FTPS: Port 990

telnet YOUR_PRINTER_IP 8883

Check firewall rules
Ensure Bambuddy server can reach printer
Check both server and network firewalls

Connection Drops Frequently¶

Symptoms: Printer connects but disconnects intermittently

Solutions:

Check WiFi signal strength
View signal strength on printer card
Move printer closer to router if weak
Network congestion
Too many devices on network
Try a dedicated network/VLAN
Router issues
Restart router
Check for firmware updates
Disable "smart" features that may interfere
Check Bambuddy logs
```
tail -f logs/bambuddy.log
```
Enable FTP retry
Go to Settings > General > FTP Retry
Enable retry with 3 attempts and 2 second delay
Increase connection timeout (default 30s) for slow WiFi
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:

Update to latest Bambuddy version
Version 0.1.6+ automatically handles A1 SSL compatibility
No manual configuration required
Increase FTP timeout for weak WiFi
Go to Settings > General > FTP Retry
Increase connection timeout from default 30s to 60-120s
A1 printers often have weaker WiFi signal than X1C/P1S
Improve WiFi signal
A1 printers are known to have weak WiFi reception
Check signal strength on printer card (-30 to -50 dBm = excellent, -50 to -70 dBm = fair, below -70 dBm = weak)
Move printer closer to router or add a WiFi extender
Enable FTP retry
Go to Settings > General > FTP Retry
Enable retry with 3-5 attempts and 2-3 second delay
Combined with longer timeout, helps recover from transient failures

Wrong Printer Status¶

Symptoms: Status shows idle when printing, or vice versa

Solutions:

Wait for sync
Status updates every few seconds
Refresh the page
Check MQTT debug
Enable MQTT debug logging
Verify messages are being received
Restart connection
Delete printer from Bambuddy
Re-add with correct details

Printer Looks Like It's Trying to Re-Start the Last Print After Power-On¶

Symptoms: Every time you power the printer on, the touchscreen shows the last printed file's name, and it looks as though Bambuddy or the printer is about to start that print again.

This is the printer's firmware, not Bambuddy. The Bambu Lab firmware (A1, A1 mini, P1, X1, H2D) keeps the last gcode_file and subtask_name in its MQTT status payload after a print finishes. Those fields persist across power cycles and are echoed in every status push, even when the printer is sitting idle. The touchscreen displays them too.

Bambuddy only acts on a real state transition (IDLE → PREPARE / RUNNING). It never sends a print command just because the last filename is still visible. You can confirm this in your support bundle log — a queued auto-start always shows up as a print_scheduler "Queue check" → "Starting queue item N" → PRINT COMMAND line. If you don't see those lines around the power-on time, Bambuddy isn't starting anything.

What to check on the printer:

Touchscreen prompt — if a "Resume last print?" or "Start print?" dialog is open, dismiss it on the printer itself.
HMS errors — codes like 0500_C010 (MicroSD card read/write exception) can leave the printer in a state where the touchscreen still shows a print as "ready". Reseat or replace the MicroSD card; if the error persists, contact Bambu Lab Support.
Saved task on the printer — the printer may keep the file in its own queue/history. Clear it from the printer's storage UI directly.

If you have already deleted the queue item in Bambuddy and removed the file from the printer's backup/cache folder and it still happens, the issue is with the printer firmware or hardware, not with Bambuddy.

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:

Ensure SD card is inserted
An SD card is required for Bambuddy to work with your printer
Check that the SD card is properly inserted in your printer
The printer should recognize the SD card in its file browser
Check SD card health
Try a different SD card if transfers fail frequently
Format the SD card using the printer's built-in format function
Use a high-quality SD card (Class 10 or better recommended)
SD card full
Check available space on the SD card
Delete old files from the printer's storage
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:

Check SD card is inserted
An SD card is required for archiving to work
Verify the SD card is properly inserted and recognized
Check printer connection
Must be connected during and after print
Verify green connection indicator
Check FTP access
Port 990 must be accessible
Try downloading a file manually
Check disk space
Ensure enough space for 3MF files
Clear old files if needed
Enable FTP retry for weak WiFi
P1S, X1C, A1, and other printers often have weak WiFi
Go to Settings > General > FTP Retry
Enable retry with 3-5 attempts and 2-3 second delay
Increase connection timeout to 60-120s for A1/A1 Mini
This helps when FTP transfers fail intermittently

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:

Update to latest Bambuddy version
Version 0.1.9b+ fixes the timelapse detection logic
No manual configuration required
Manual scan if auto-detection missed
Open the archive
Click Scan for Timelapse button
This uses print-name matching and timestamp proximity
Check printer storage
Ensure the SD card has enough free space
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:

Update to latest Bambuddy version
Version 0.1.9b+ automatically filters calibration prints
Delete unwanted calibration archives
Search for "auto_cali" in the archives search bar
Select and delete any unwanted calibration archives

Duplicate Archives¶

Symptoms: Same print appears multiple times

Solutions:

Enable duplicate detection
Go to Settings > General
Enable duplicate detection
Clean up duplicates
Filter archives by name
Delete unwanted duplicates

Missing Thumbnails¶

Symptoms: Archive cards show placeholder instead of thumbnail

Solutions:

Check 3MF file
Some files don't include thumbnails
Re-slice with thumbnail enabled
Regenerate thumbnails
Bambuddy can regenerate from 3MF
Check Settings > Maintenance

Wrong Plate Thumbnail on Printer Card During a Multi-Plate Print¶

Symptoms: The printer card shows a thumbnail from a different plate than the one currently printing.

Cause: Some firmware versions (e.g. P1S 01.10.00.00) only put the bare .3mf filename in the MQTT gcode_file field, omitting the Metadata/plate_N.gcode path. Without the plate path the cover route used to default to plate 1's thumbnail.

Resolution: Fixed in 0.2.4b2. Bambuddy now records the plate it dispatched at publish time and prefers that record over parsing the gcode path. For prints started outside Bambuddy (e.g. Bambu Studio direct), the cover route additionally scans the downloaded 3MF for a unique Metadata/plate_*.gcode to identify the active plate. If you still see the wrong thumbnail on 0.2.4b2 or later, ensure the print was dispatched from Bambuddy and capture a support package — the resolved plate is logged at INFO level (Cover: resolved plate N).

Cover Thumbnail Stuck Loading During an Active Print¶

Symptoms: Printer card shows a loading state instead of a thumbnail; logs show FTP connection timed out to the printer.

Cause: Bambu printers run a single-socket FTP server that prioritises the active print. While a print is running, concurrent FTP reads (for the cover thumbnail) sometimes time out — especially on large 3MF files (50 MB+) where the read window is tight. An aborted upload to the printer can also wedge the FTP session until the printer is restarted.

Resolution: As of 0.2.4b2, Bambuddy registers the local archive 3MF in the cover-cache at dispatch time, so the cover route reads the file straight from disk rather than refetching it over FTP. This applies to any print dispatched from Bambuddy (archive card, file manager, queue). If you see this on a Studio-direct print:

Wait — the cover route caches successful downloads, so once it makes it through once subsequent loads are instant.
If FTP repeatedly times out, restart the printer to clear any stuck FTP session from a previous aborted upload.

Camera Issues¶

Camera Won't Stream¶

Symptoms: Camera page shows error or black screen

Solutions:

Check ffmpeg installation
```
ffmpeg -version
```

Install if missing:

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

Verify camera is enabled
Check printer settings
Camera must be enabled in printer settings
Check connection
Camera requires active printer connection
Verify printer shows as connected
Try snapshot mode
Click "Snapshot" instead of "Live"
May work when streaming doesn't

Stream Freezes¶

Symptoms: Video starts but freezes

Solutions:

Network bandwidth
Lower FPS setting
Check network congestion
Check ffmpeg processes
```
ps aux | grep ffmpeg
```

Kill orphaned processes:

killall ffmpeg

Refresh the stream
Click refresh button
Close and reopen camera page

Notification Issues¶

Notifications Not Sending¶

Symptoms: No notifications received

Solutions:

Test the provider
Go to Settings > Notifications
Click "Send Test"
Check for errors
Verify configuration
Double-check API keys/tokens
Verify phone numbers include country code
Check quiet hours
Notifications suppressed during quiet hours
Verify current time vs quiet hours setting
Check event triggers
Ensure desired events are enabled
Check printer filter settings

Notification Variables Empty¶

Symptoms: Messages show "Unknown" or blank for variables

Solutions:

Update to latest version
Variable handling improved in recent versions
Check print data
Some variables require specific print data
May show "Unknown" for incomplete prints

Database Issues¶

Database Errors¶

Symptoms: 500 errors, data not saving

Solutions:

Check disk space
```
df -h
```

Verify database integrity

sqlite3 bambuddy.db "PRAGMA integrity_check;"

Restore from backup
If corrupted, restore from backup
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:

Update to latest Bambuddy version
WAL mode is automatically enabled on startup — no configuration needed
Check for WAL files
SQLite WAL mode creates bambuddy.db-wal and bambuddy.db-shm files next to the database
These are normal runtime files and should not be deleted while Bambuddy is running
They are cleaned up automatically when the database is closed properly
Docker volume mounts
Ensure the data directory volume has sufficient write permissions
WAL files must be on the same filesystem as the database

Search Not Working¶

Symptoms: Search returns no results or wrong results

Solutions:

Rebuild FTS index
Go to Settings > System Info
Click "Rebuild Search Index"
Check search syntax
Use quotes for exact phrases
Check for typos

Smart Plug Issues¶

Tasmota Plug Not Responding¶

Symptoms: Can't control Tasmota smart plug

Solutions:

Verify IP address
Check plug still has same IP
Use static IP or DHCP reservation
Test Tasmota interface
Open http://PLUG_IP in browser
Verify Tasmota web interface loads

Check network access

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

REST/Webhook Plug Not Responding¶

Symptoms: Can't control REST/Webhook smart plug

Solutions:

Test the URL with curl

curl -X POST "http://your-device:8080/api/endpoint" -d "ON"

Verify network access
Ensure the target service is reachable from Bambuddy's network
Check headers
Custom headers must be valid JSON (e.g., {"Authorization": "Bearer token"})
Check HTTP method
Ensure the method (GET/POST/PUT/PATCH) matches what the target API expects
Check the target service's logs
Look for authentication errors or invalid request formats

Auto Power-Off Not Working¶

Symptoms: Printer doesn't turn off after print

Solutions:

Check feature is enabled
Settings > Smart Plugs > Auto Power Off
Verify cooldown settings
Check temperature threshold
Check cooldown time
Check for queued prints
Won't power off if more prints queued

Virtual Printer Issues¶

Slicer shows no AMS / no filament slots / no temperatures¶

If your VP has a target printer configured, the slicer should show live AMS slots, FTS / dual-extruder routing, k-profiles, temperatures, and the camera stream — same view as a direct slicer connection. If the panel is empty, check:

Target printer set? Settings → Virtual Printer → check the VP has a target printer selected. The mirror only runs when this is set.
Target printer connected? Bambuddy must be online with the real printer (Settings → Printers shows green status). The bridge has nothing to mirror if Bambuddy itself isn't talking to the printer.
Restart Bambuddy after setting the target — the bridge attaches at VP startup.

If your VP has no target printer set, the slicer sees synthetic stub state by design — the VP is a pure file receiver. Set filaments manually, hit Send, then dispatch to a real printer from Bambuddy's UI later. To enable live mirror, set a target printer in Settings → Virtual Printer.

See the Virtual Printer guide for the full explanation.

Slicer camera shows "LAN connection failed"¶

Camera streaming requires the VP's access code to match the target printer's LAN access code. The slicer authenticates the camera RTSPS stream with the access code stored in its profile, and that auth happens against the real printer. Fix:

Settings → Virtual Printer → set the VP's access code equal to the target printer's LAN access code (Settings → Printers shows the printer's code)
Re-add the VP in Bambu Studio / Orca Slicer so it picks up the new code

MQTT and FTP work either way — only the camera path needs the access codes to match.

Slicer can't find the Virtual Printer¶

See Slicer Can't Find or Connect to Virtual Printer in the Virtual Printer guide — covers SSDP, bind ports (3000/3002), TLS certificate, and cross-subnet setups.

Print Queue Issues¶

Next queued print auto-started without "Clear Plate" confirmation¶

Symptoms: You have Auto Off enabled and a queue of prints. When one print finishes, the smart plug cuts power; the plug immediately re-powers the printer because the next job is queued; the next print then starts without showing the Clear Plate & Start Next prompt.

Background:

Before Bambuddy v0.2.3b4, the plate-clear gate lived only in memory and was tied to the printer's reported state (FINISH / FAILED). When the plug re-powered the printer, it booted fresh into IDLE with no memory of the previous finish, so the scheduler's idle check saw a normal idle printer and dispatched the next job immediately — bypassing the confirmation (#961).

Solutions:

Update to Bambuddy v0.2.3b4 or later — the gate is now persisted to the database and keyed off an explicit "awaiting acknowledgment" flag instead of the reported state. The prompt survives Auto Off power cycles, Bambuddy restarts, and the printer booting back into IDLE.
If the prompt still doesn't appear after the update, confirm Require plate-clear confirmation is enabled in Settings → Queue.
Dismissing a stale prompt — if Bambuddy thinks the plate is still uncleared but you've already removed the print (e.g. after a crash), just tap Clear Plate & Start Next. The scheduler will dispatch the next job if one is queued; if the queue is empty the flag is simply cleared.

General Issues¶

Bambuddy Won't Start¶

Solutions:

Check Python version
```
python3 --version  # Need 3.10+
```
Check dependencies
```
pip install -r requirements.txt
```
Check port availability
```
lsof -i :8000
```
Check logs
```
cat logs/bambuddy.log
```

Slow Performance¶

Solutions:

Check system resources
```
htop
```
Vacuum database
Settings > System Info > Vacuum Database
Clear old logs
Logs rotate automatically
Delete very old log files if needed
Check for runaway processes
```
ps aux | grep -E "ffmpeg|python"
```

Getting More Help¶

Information to Gather¶

When reporting issues, include:

Bambuddy version - Settings > About
Printer model - X1C, P1S, etc.
Operating system - Linux, macOS, Windows
Installation method - Docker, manual
Steps to reproduce - What you did
Error messages - Exact text
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