Troubleshooting¶

Solutions for common issues with Bambuddy.

Printer Connection Issues¶

Run the Connection Diagnostic first¶

Before working through the steps below, let Bambuddy check for you. The built-in Connection Diagnostic runs the same checks a maintainer would: port reachability (MQTT 8883, FTPS 990, RTSPS 322), LAN Developer Mode, container network mode, printer/host subnet match, printer credentials, and the printer-side "Store sent files on external storage" toggle (install step 4). Each result comes with a plain-language fix.

Open it from any of:

• The printer card — a Run diagnostic button appears when a printer is offline.
• The Add Printer dialog — Run diagnostic tests the address and credentials before you save.
• System page → Connection Diagnostic — run it for any configured printer on demand.

Most "won't connect" and "won't print" problems are identified here in a few seconds.

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. If the printer actively refused the code, the log says so: MQTT connection refused by the printer: Not authorized. Run the Connection Diagnostic — the Printer credentials check names the cause when the printer told us, and hedges when all Bambuddy knows is that there is no session (a rebooting printer, or one already at its limit of simultaneous connections, looks the same from outside).

12. Check network connectivity

    ping YOUR_PRINTER_IP
    

13. Verify ports are accessible

14. MQTT: Port 8883
15. 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

The Printer Accepts Every Job and Starts None of Them¶

Symptoms: The 3MF uploads fine, the queue item goes to Printing, and the printer stays idle. After a few minutes the job fails. Temperature and filament controls report success and the printer ignores them. Printing the same file straight from Bambu Studio or OrcaSlicer works.

Cause: the printer rejected the command because it could not verify it — HMS 0500-0500-0001-0007, MQTT command verification failed. Bambu Lab firmware from 01.08.03.00beta / 01.08.05.00 authenticates control commands, and Developer Mode is the documented way to turn that off for LAN control.

This is confusing to diagnose because the printer keeps answering queries normally. Status, AMS contents, RFID tags and the camera all keep working, so the connection looks perfectly healthy — only commands are being dropped.

Fix:

1. On the printer: Settings > Network, turn on LAN Only Mode, then enable Developer Mode (it appears once LAN Only Mode is on).
2. Restart the printer. The setting does not take effect until it reboots.
3. Re-check the access code — it changes when the mode is toggled.
4. Start the job again.

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:

1. Touchscreen prompt — if a "Resume last print?" or "Start print?" dialog is open, dismiss it on the printer itself.
2. 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.
3. 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:

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

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
    

Archive Card Has Only a Name¶

Symptoms: The print is archived with its name and timing, but there is no thumbnail, no filament total, no layer count, and the Reprint button is greyed out. Other printers on the same Bambuddy install archive normally.

Background:

Bambuddy reads a print's 3MF and its cover over FTPS on port 990. On every Bambu model that port serves external storage only — the SD card or USB stick. It is not a view of the printer's whole filesystem.

On H2-series, P2S and X2D, Bambu Studio puts the sliced file on the printer's internal storage instead, uploading over a separate service on port 6000.

That is where the printer put it, which is not always the same as where FTPS can read it. Some H2D firmware keeps a copy of the same file under /cache on the card and hands it over on request, and those prints archive in full. So Bambuddy looks before it gives up: the printer names the exact file, and checking for it costs one connection. Where no copy exists — an H2C or P2S with the file only on internal storage — there is nothing to fetch at any path, and the archive holds only what the printer reported over MQTT.

What decides it is the slicer, not the printer and not your settings. Measured on an H2C, an H2D and an X1C — same Bambu Studio, same model, one minute apart, all three reporting "Store sent files on external storage" as on:

Treat the last column as "what those printers did on that day", not a rule: a later H2D report (#2856) had the same brtc://emmc dispatch with a perfectly readable copy on the card, which is why Bambuddy now checks each print rather than reading the answer off the URL.

The X2D behaves like the H2 series. That one is not from the run above but from a user report (#3126), whose log carries the same brtc://emmc dispatch with a card in the slot and OrcaSlicer archiving the same project in full on the same printer.

The same H2C and H2D sliced in OrcaSlicer put the file on the card and archived in full, and turning "Store sent files on external storage" off made no difference to that — OrcaSlicer always uploads over FTPS. So the toggle does not control this on H2-series, P2S or X2D, in either direction.

Bambu Studio's Send dialog does offer a storage picker — Cache (the printer's internal memory) or External — and choosing External puts the file on the card where Bambuddy can read it. Its Print button offers no such choice (tested on an H2D) and goes to Cache every time. So staying in Bambu Studio means sending first and starting the print as a second step. BambuStudio#10481 tracks the default.

You can tell which storage a print used from the log:

grep '"url"' logs/bambuddy.log

"url": "ftp://<name>" means the card, and the archive will be complete. "url": "brtc://emmc/<name>" means internal storage — then the next lines say how it ended: Downloaded: /cache/<name> if the printer kept a readable copy after all, or Skipping the 3MF lookup if it did not.

Solutions:

All the routes below need a card or stick in the printer. On X1 and P1 series, where Bambu Studio already uses external storage, only the first point applies.

1. Insert a card or stick

   • Check Settings > Printers > Connection Diagnostic: Store sent files on external storage reports no_media when the slot is empty
   • The setting itself lives in the printer's own Print Settings on current firmware, and in Bambu Studio / OrcaSlicer's Device tab on older versions. It is worth having on, but on H2-series, P2S and X2D it will not change where Bambu Studio sends the file

2. Start the print from Bambuddy instead of the slicer

   • Bambuddy uploads over FTPS itself, so the file lands on external storage and the archive is complete, on every model

3. Slice in OrcaSlicer

   • OrcaSlicer always uploads over FTPS, so its prints archive in full on H2-series too
   • It will refuse to send with an empty slot — "storage needs to be inserted before printing via lan" — rather than silently falling back to internal storage

4. Send from Bambu Studio with External picked, then start the print

   • The picker is in the Send dialog only; Print always uses Cache
   • Start it from the printer's own screen, from Handy, or from Studio's device page — all three archive in full
   • Two steps rather than one, but it keeps you in Bambu Studio

5. Accept the partial archive

   • Name, timing, status, and the finish photo still work; only the slicer-derived data is missing

Archive Card Is Empty After a Slow Transfer¶

Symptoms: The archive holds a name and timing but no thumbnail and no slicer data, on a printer whose other prints archive fine. It happens on big files, on prints started while the printer was busy, or on a worn SD card. The log says the download timed out rather than that the file was missing:

FTP download timed out after 30.0s (plus 30.0s grace) for /<print>.gcode.3mf
Download 3MF from /<print>.gcode.3mf failed after 4 attempts
Could not find 3MF file for print: <print>.gcode.3mf

Background:

The file is on the card and the printer is serving it. What ran out was time. Bambuddy fetches a print's 3MF at the moment the print starts, which is the busiest moment the printer has: it is streaming its camera, publishing status over MQTT, and often still finishing the upload of the job itself. A large 3MF against all of that does not reliably finish inside the transfer budget, and the same file downloads in seconds once the printer settles.

This is the one empty-archive cause where the card was never the problem, so the usual advice — check "Store sent files on external storage", check the slot — does not apply. You can tell it apart from a genuinely missing file by the log lines above: a file that is not on the card is answered with 550 and Bambuddy moves straight to the next path, without a timeout.

What Bambuddy does about it on its own:

From 1.2.6, a print that ends this way is not given up on. Bambuddy goes back for the file after one minute, four minutes and ten minutes, and fills the archive in where one of those lands — the thumbnail, the filament totals and the layer count all appear on the existing card, and the empty-archive banner stops counting it. Opening the print's card in the meantime does the same thing sooner, because the cover has to fetch the file anyway.

So a card that is still empty an hour later is one where every attempt also ran out of time.

Solutions:

1. Raise the transfer timeout

   • Settings > Network > FTP Retry > Connection Timeout, up to 300 seconds
   • It is a database setting and takes effect immediately — no restart, no rebuild
   • Worth doing on any install that prints files over ~15 MB, and on A1 and P1 series generally

2. Check the card

   • A worn card is the usual reason a transfer that used to fit no longer does: the same 5.4 MB file measured 45 s off a worn P1S card and 25 s off a new one
   • Cards are consumables; replacing one is cheaper than the time spent on this

3. Give the printer less to do at print start

   • Closing the camera stream on the Dashboard while a print starts leaves more of the printer's link for the transfer
   • Starting the print from Bambuddy rather than the slicer avoids Bambuddy and the slicer competing for the same connection

Print Started on the Printer Has No Thumbnail¶

Symptoms: The archive holds a name and timing but no thumbnail, no filament total and no layer count — and it happens only for prints you started from the printer's own screen, from Handy, or by picking a file the printer already had. Prints sent from a slicer on the same machine archive in full.

Background:

This is the section above with the slicer taken out of it. Nothing was sent for these prints: the file was already on the printer, in its own model library, and starting it from the screen only tells the firmware which one to run.

That library lives on the printer's internal storage under /userdata/model/history/, and port 990 does not serve it. So there is no .gcode.3mf for Bambuddy to read, and no slicer setting changes that — "Store sent files on external storage" governs where a slicer puts a file it is sending, and nothing was sent.

The printer announces where the file lives when the print begins, and Bambuddy reads it:

grep 'Print destination from the report topic' logs/bambuddy.log

file:///userdata/model/history/<name>.gcode.3mf is this case. Bambuddy still checks before giving up, because some printers keep a copy of recently used jobs under /cache and hand it over — those prints archive in full, thumbnail included. The copy is what rotates out: on an H2S /cache holds about eight files, so the same job archives completely today and partially next month.

Solutions:

1. Fill in what the printer knows

   • The printer's own file browser lists the sliced weight and print time for each job in its library
   • Open the archive, choose Edit Archive, and enter it under Filament used (g) — the cost follows from it, and the Projects and statistics totals pick it up

2. Start the print from Bambuddy

   • Bambuddy uploads over FTPS itself, so the file lands where it can be read back and the archive is complete

3. Re-send from the slicer instead of re-printing from the library

   • A re-print of a job you still have in the slicer archives in full when it is sent again, on any model where the slicer uploads over FTPS

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 announce their own calibration routines over MQTT through the same print-start event a real print uses, so Bambuddy has to recognise them by name. Four shapes exist and all of them are filtered:

Filtered runs create no archive and send no print-started or print-completed notification.

The match is exact, so a file you have deliberately named after a calibration - auto_pa_line_calib_mode_v2.3mf, or your own calibration cube - is still archived as the print it is.

Solutions:

1. Update to latest Bambuddy version

2. v1.2.6+ filters every routine above

3. Delete unwanted calibration archives

4. Search the archives for auto_cali or auto_pa_line to find rows created before the upgrade
5. Select and delete any you don't want

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

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¶

Every camera stopped after updating to 1.2.5.4¶

Symptoms: live view shows "Connection lost" on every RTSP printer (X1, H2, P2) at once, and the in-app Camera Diagnostic reports capture_exception at 0 ms while network reachability passes. A1 and P1 are unaffected.

That 0 ms is the tell — the failure happens before a socket is opened. Bambuddy is running on uvloop, which it is not shipped on. Fixed in 1.2.5.5, but the underlying misconfiguration is worth correcting because it also risks silently truncated Virtual Printer uploads — see Uploads to the VP arrive corrupt.

Check which loop your service uses:

systemctl show bambuddy --property=ExecStart --value | grep -o -- '--loop [a-z]*'

No output means no loop is pinned, so uvicorn picks uvloop. Running install/update.sh (or update_macos.sh) from 1.2.5.5 onwards adds the flag for you and backs the file up first. To do it by hand, add --loop asyncio to the uvicorn command in your service file and restart.

This affects installs whose service file Bambuddy's own installer did not write — the Proxmox VE Helper-Scripts LXC composes its own — and native installs created before 2026-07-05, since updating has never rewritten an existing service file. Docker is unaffected: the image pins the flag itself.

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

10. Check for a second connection to the camera

    Most Bambu printers accept exactly one camera connection at a time — the chamber-image socket on port 6000 (A1 / P1), or the RTSP socket on port 322 (X1 / H2 / P2). Bambuddy therefore opens one connection per printer and fans it out to every viewer (camera page, cam-wall tile, embedded viewer, popup) rather than one per viewer.

    If a second connection ever overlaps, the printer keeps feeding the first one and the newcomer receives nothing — the page goes black and stays black until the printer's TCP keepalive reaps the orphan, which takes around 20 minutes. A black stream that recovers on its own after roughly that long is the signature.

    While the screen is black, check how many connections the printer has:

    # A1 / P1 (chamber image)
    ss -tn | grep :6000
    
    # X1 / H2 / P2 (RTSP)
    ss -tn | grep :322
    

    More than one line means something is holding an extra socket open — another tool talking to the same printer (Bambu Studio, Home Assistant, a second Bambuddy instance) is the usual cause. Close it and reload the camera page.

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

Server CPU Pinned While Cameras Are Open¶

Symptoms: CPU (and often RAM) maxed out on a multi-printer setup; ffmpeg processes at the top of top or docker stats

Background:

On X1, X2, H2 and P2 printers the camera arrives as H.264 over RTSP, which a browser cannot display directly, so Bambuddy transcodes it to MJPEG in software. Budget roughly one CPU core per open 1080p stream. A1 and P1 printers use a different protocol with no transcode and are close to free.

This is a limit of the transcode, not a misconfiguration — and it is reached by the number of cameras open at once, not by the number of printers you own.

Solutions:

1. Confirm it is cameras — close every camera window and kiosk tab, switch the Printers page to card view, and see whether the load drops. Bambuddy never streams a camera that nobody is watching.
2. Lower the Cam Wall live-stream count and raise the snapshot interval, on every browser and kiosk showing a wall.
3. Check AI failure detection is off, or scoped to specific printers — with nothing selected it monitors every printer continuously.

See Running a Large Farm for the measured numbers, the full set of knobs, and the work under way to remove the transcode.

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
14. Obico spaghetti detections: enable the dedicated AI Failure Detection toggle, not "Printer Error" — AI alerts moved to their own event (see Failure Detection)

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

10. Move to PostgreSQL if you run more than ~10 printers

11. SQLite allows only one writer at a time across the whole database, and WAL plus the busy timeout only absorb short collisions. On a large farm, dispatch and completion writes overlap constantly and some of them are not retried
12. See PostgreSQL Support and Running a Large Farm

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¶

Tasmota Plug Not Responding¶

Symptoms: Can't control Tasmota 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"
   

REST/Webhook Plug Not Responding¶

Symptoms: Can't control REST/Webhook smart plug

Solutions:

1. Test the URL with curl

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

2. Verify network access

3. Ensure the target service is reachable from Bambuddy's network

4. Check headers

5. Custom headers must be valid JSON (e.g., {"Authorization": "Bearer token"})

6. Check HTTP method

7. Ensure the method (GET/POST/PUT/PATCH) matches what the target API expects

8. Check the target service's logs

9. Look for authentication errors or invalid request formats

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

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:

1. Target printer set? Settings → Virtual Printer → check the VP has a target printer selected. The mirror only runs when this is set.
2. 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.
3. 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:

1. 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)
2. 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 uploads fail at ~10% ("Failed to send") in Docker bridge mode¶

Symptoms: The VP is added manually by the Docker host's IP. Detection, MQTT, status, and camera all work, but sending a print job fails around 10% with "Failed to send". A tcpdump shows the bind/detect exchange (port 3002) succeed and then the session close — with no connection ever attempted to FTPS port 990 or the passive-data ports.

Cause: The upload is the one flow where the printer advertises its own IP to the slicer as the FTP target. Inside a default-bridge container the only address that exists is the NAT IP (e.g. 172.17.0.10), so that's what gets advertised — and your LAN client has no route to it, so the FTP connection never leaves the machine. The container cannot discover the host's real LAN IP on its own, and VIRTUAL_PRINTER_PASV_ADDRESS only overrides the FTP passive-data address, not the advertised identity (and the slicer never reaches the FTP stage to use it).

Resolution: Either tell the container which address to advertise, or give it a LAN-routable one of its own.

Quickest fix, if you need to stay on bridge networking (#2930) — set both to your Docker host's LAN IP and restart the container:

environment:
  - VIRTUAL_PRINTER_ADVERTISE_ADDRESS=192.168.1.100
  - VIRTUAL_PRINTER_PASV_ADDRESS=192.168.1.100

VIRTUAL_PRINTER_ADVERTISE_ADDRESS replaces the advertised identity, which is the part that was sending your slicer to 172.17.0.10. Check the log for the line confirming which address the VP is handing out:

MQTT bridge IP encoding armed: target=192.168.1.42 vp=192.168.1.100 (VIRTUAL_PRINTER_ADVERTISE_ADDRESS)

If it says (bind_address) or (auto-resolved) instead, the variable didn't reach the container. A malformed value is ignored with a warning naming it, and the VP falls back to the address it would have used before.

Better fix, and the mode Virtual Printer is developed against — give the Virtual Printer a LAN-routable identity, so nothing needs overriding:

• network_mode: host (recommended, Linux) — the container uses the host's LAN IP directly.
• macvlan — the container gets its own real LAN IP, so it stays reachable from your other Docker services (behind Caddy/Authentik, etc.) while also being routable for uploads.

See Docker (macOS / Windows) in the Virtual Printer guide for the bridge-mode warning and the host/macvlan setups.

Uploads to the VP arrive corrupt / the real printer can't start the job¶

If files sent to a Virtual Printer are archived and queued but the physical printer then fails to parse or start them — and the received .gcode.3mf is smaller than what the slicer exported (often ending at an exact multiple of 4096 bytes) — your server is likely running under uvloop, whose SSL layer can silently drop the tail of an upload on slow storage (e.g. a microSD / eMMC on an SBC).

Fix: launch uvicorn with --loop asyncio. The Docker image already does this; native installs must add it to the run command / service unit:

uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 --loop asyncio

From 1.2.5.5, running install/update.sh (or update_macos.sh) adds the flag to an existing service file for you, backing it up first; Bambuddy also logs a warning at startup whenever it finds itself on uvloop. Otherwise re-run the installer or edit your systemd unit / launchd plist / NSSM service to include --loop asyncio, then restart Bambuddy. Bambuddy 0.2.5b2+ also validates every received .3mf is a complete ZIP before accepting it — a truncated upload is now rejected with an FTP 426 (an immediate send error in the slicer) instead of being archived and forwarded to the printer.

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:

1. 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.

2. If the prompt still doesn't appear after the update, confirm Require plate-clear confirmation is enabled in Settings → Workflow → Queue & Dispatch.

3. 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.

Print fails with "Failed to get AMS mapping table" or a nozzle-size error¶

Symptoms: You slice a file in Bambuddy and send it to the printer, and the printer immediately rejects it with an HMS error such as "Failed to get AMS mapping table; please select 'Resume' to retry" (code 0700_8012) or "The nozzle diameter in the sliced file is not consistent with the current nozzle setting" (code 0500_4038). A related giveaway: when configuring an AMS slot, the filament-profile picker only offers 0.4 mm profiles even though a different nozzle (e.g. 0.6 mm) is installed.

Background:

These errors mean the file was sliced for a different nozzle diameter than the one physically installed on the printer. Two things contributed before Bambuddy v0.2.5b2:

• The Configure AMS Slot picker assumed a 0.4 mm nozzle regardless of the hardware, so it filtered out the 0.6 mm (or 0.2 / 0.8 mm) filament profiles you needed — you couldn't set your trays to the profile that matched the slice (#1899).
• Bambuddy did not check the sliced nozzle size against the installed nozzle before dispatch, so a mismatch only surfaced later as the printer's cryptic HMS error.

Solutions:

1. Update to Bambuddy v0.2.5b2 or later. The AMS Slot picker now reads the nozzle actually installed on the printer (per-nozzle on dual-nozzle H2D) and offers the matching profiles. Bambuddy also validates the sliced nozzle size before sending the job and, on a mismatch, fails the queue item with a clear message — "File sliced for a 0.6mm nozzle, but the printer has 0.4mm installed" — instead of letting the printer throw the HMS error.

2. Make the nozzle sizes agree. Either re-slice the file for the nozzle that's installed, or install the nozzle the file was sliced for. Bambuddy filters filament and process profiles by the selected printer preset's nozzle size, so pick a printer preset whose name matches your installed nozzle (e.g. … 0.6 nozzle) when slicing.

3. Confirm the printer reports the right nozzle. The printer card shows the detected nozzle diameter (e.g. "• 0.6mm") next to the model in expanded view. If it's wrong or missing after a nozzle swap, the printer firmware may not have re-detected it yet — power-cycle or re-home the printer so it re-reads the installed nozzle, then reconnect in Bambuddy.

AMS & Filament Issues¶

AMS slot shows my custom filament, the printer shows Generic¶

Symptoms: You assign a custom filament preset to an AMS slot with Configure Slot. Bambuddy's slot card shows the custom name correctly, but the printer's own screen and Bambu Studio's Device tab both show a generic filament — Generic PLA, Generic ABS — instead.

Background:

The three surfaces are not reading the same thing. Bambuddy shows the preset you picked, stored next to the slot. The printer and the slicer show what the printer resolved from the slot's eight-character filament ID. Two things stop a custom preset reaching that field as itself:

1. The preset has no filament ID of its own. A preset that only overrides fields of a generic base has none, and neither does an OrcaSlicer preset synced to Bambu Cloud. There is nothing custom to send, so the slot stays on a filament ID that does resolve — and the printer names that filament.
2. The printer has never fetched your filament list from Bambu Cloud. Developer Mode is LAN-only by Bambu's design, so a printer that has never been cloud-connected holds no custom-filament data to resolve a name against.

Solutions:

1. Work out which of the two it is. Open the preset in Bambu Studio. Created as a genuinely new filament? It has its own ID, so you are in case 2. Only editing a generic base? Case 1 — there is nothing custom to send, and no setting will change that.

2. For case 2, let the printer cache the preset once. Put the printer in cloud mode, open its filament settings screen so it pulls your presets down, then switch back to LAN Only + Developer Mode. See Why the printer may still show a generic filament.

3. Update to 1.2.6b1 or later. Before that release the full cloud preset ID was sent into the eight-character field, so it arrived truncated: the slot pointed at nothing resolvable and lost its calibration entry too.

Backup Issues¶

Backups fail with "Read-only file system"¶

Symptoms: Scheduled or manual backups to a NAS share, USB drive or any path outside the Bambuddy install fail with [Errno 30] Read-only file system. Your own shell can write to that directory, the permissions look correct, and existing backups in the folder still show up in the list.

Cause: This is not a permission problem -- errno 30 is EROFS, a permission problem would be errno 13. On a systemd install, Bambuddy runs with ProtectSystem=strict, which makes every directory outside the install, data and log directories read-only for the service, no matter what its owner and mode say. Reads are unaffected, which is why the backup list still works.

Solution (systemd): allow the path in a drop-in, which survives reinstalls and upgrades.

sudo systemctl edit bambuddy

[Service]
ReadWritePaths=/mnt/nasbackup

sudo systemctl restart bambuddy
systemctl show bambuddy -p ReadWritePaths   # confirm

Solution (Docker): bind-mount the path into the container -- see Backup & Restore.

Bambuddy now checks the output directory when you save it and reports exactly this, with the command to fix it. If the share itself is genuinely mounted read-only (a stale CIFS/NFS mount after a network blip does this), remount it -- findmnt -no OPTIONS /mnt/nasbackup will show ro.

General Issues¶

Bambuddy needs Python 3.11 or newer¶

A native install whose environment was created with Python 3.10 or older stops starting from v0.2.4.8, and the update script refuses to update it until it has been moved to Python 3.11 or newer. Docker and the Windows installer are not affected.

The steps below assume the installer's defaults: install path /opt/bambuddy, service user and service bambuddy. Adjust them if you chose others.

1. Install Python 3.11 or newer with its venv module:
   • Ubuntu 22.04: sudo apt install python3.11 python3.11-venv
   • Debian 12, Ubuntu 24.04, Raspberry Pi OS bookworm and newer already have it (python3).
   • Debian 11 / Raspberry Pi OS bullseye have no Python 3.11 package: upgrade the system, or use Docker.
2. Rebuild the environment with it (Bambuddy's data and settings are not in it):

   sudo systemctl stop bambuddy
   cd /opt/bambuddy
   sudo -u bambuddy python3.11 -m venv --clear venv
   sudo -u bambuddy venv/bin/pip install --upgrade pip
   sudo -u bambuddy venv/bin/pip install -r requirements.txt
   sudo systemctl start bambuddy
   

   Use python3 instead of python3.11 where that is already 3.11 or newer. On macOS run the same commands in your install folder without sudo -u bambuddy, with Homebrew's python3.
3. Run the update again.

Bambuddy Won't Start¶

Solutions:

1. Check the Python version of Bambuddy's environment (not the system's python3, which may be older)

   /opt/bambuddy/venv/bin/python --version  # Need 3.11+
   

   If it is older, see Bambuddy needs Python 3.11 or newer.

2. Check dependencies

   pip install -r requirements.lock
   

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"
   

System Health Checks¶

Bambuddy scans its own recent log against a catalog of known issues and surfaces what it finds on the System page → System Health section and inside the in-app bug reporter. Each finding links here. The checks below cover the issues that catalog can detect — most are setup problems you can fix yourself.

Printer rejected the access code¶

Bambuddy's file-transfer login was refused by the printer. The access code is wrong, or it changed — the printer generates a new access code every time LAN Developer Mode is toggled.

Re-copy the access code from the printer screen (Settings → LAN) and update it under the printer's settings in Bambuddy. See also Printer Won't Connect.

File-transfer connection timed out¶

Bambuddy could not reach the printer's file-transfer port (FTPS 990). The port is blocked by a firewall, or the printer is powered off or on a different subnet.

Make sure nothing blocks port 990 between Bambuddy and the printer, and that both are on the same network. See also Prints Won't Start / File Transfer Fails.

Secure file-transfer handshake failed¶

Bambuddy opened a connection to the printer's file-transfer port (FTPS 990) and the printer answered with something that is not TLS. The log entry looks like this:

FTP SSL error connecting to 192.168.1.50: [SSL: WRONG_VERSION_NUMBER] wrong version number

What this is not. It is not the printer model, the firmware version, a TLS version mismatch, or a Bambuddy setting. The same models and firmware run normally on other installs; on one 9-printer farm three P2S units failed while three more of the same model on the same switch and the same access point never did. Probed directly on port 990, every Bambu printer measured so far -- six P2S, two X1C, an H2D -- refuses TLS 1.3 and completes on 1.2, so the negotiated version was already 1.2 and there is no version to fall back from. A genuine version mismatch reports itself as TLSV1_ALERT_PROTOCOL_VERSION; WRONG_VERSION_NUMBER is what you get when the first bytes back are not a TLS record at all.

We do not know what triggers it, and there is no fix to apply yet. Earlier revisions of this page said to power-cycle the printer. That advice has been withdrawn: the reporter who prompted it did a full power-off on both affected printers and the failure continued unchanged. The port still accepts connections -- so the Connection Diagnostic's port check and any firewall test look fine -- and a manual openssl s_client to the same printer a second later completes a clean handshake and returns a valid certificate. Restarting is harmless if you want to try it, but do not expect it to help, and please do not conclude from a restart that the problem is gone.

What would help is a capture. From 1.2.5.4, when a handshake fails this way Bambuddy opens one plain connection to port 990 and logs whatever the printer actually said, marked as the line to quote in a report:

Printer 192.168.1.50 answered port 990 in cleartext with: 421 Too many connections

If your log has that line, it is the single most useful thing you can post. If it says the printer sent nothing readable, the refusal was momentary and had already cleared. To capture one, turn on Debug Logging on the System page, wait for a print to archive with only a name, then download the Support Bundle from the same page and attach it to your report.

While a printer is in this state, anything that reads a file from it fails:

• print archives arrive with only a filename -- no filament totals, no layer count, no MakerWorld link
• cover thumbnails do not load
• timelapse scanning finds nothing

Bambuddy pauses file transfers to that printer for five minutes after a failed handshake rather than retrying every candidate path, so the log shows a handful of these entries rather than thousands. Printing itself is unaffected -- the control connection (MQTT 8883) is a separate service.

An archive caught by this recovers on its own. From 1.2.6, a print that started while the pause was running is not written off. Bambuddy re-attempts the download once the pause clears, and if anything else fetches the file first -- opening the printer card downloads it to draw the thumbnail -- the archive is filled in from that copy with no second transfer. The card gains its thumbnail, file size, filament totals and layer count while the print is still running. Recovery only applies to this pause: a print the printer kept on internal storage has no FTPS copy to come back for, and that archive stays as it is.

Also check that no firewall or TLS-inspecting proxy sits between Bambuddy and the printer, and see A1/A1 Mini FTP Issues if the printer is an A1 or A1 Mini.

Printer connection keeps dropping¶

The control connection (MQTT 8883) repeatedly disconnects and reconnects. This is usually a weak Wi-Fi path to the printer or a partially blocked port.

Check the Wi-Fi signal at the printer, prefer a wired connection, and make sure port 8883 is reliably reachable. See also Connection Drops Frequently.

Camera stream unreachable¶

The live camera could not be reached on RTSPS 322. The port is blocked, or the camera or LAN liveview is disabled on the printer. This does not affect printing.

Enable the camera and LAN liveview on the printer and make sure port 322 is not blocked. See also Camera Won't Stream.

Bambu Cloud is asking for a CAPTCHA¶

Signing in to Bambu Cloud fails with a message about confirming you are not a robot, and no CAPTCHA is shown anywhere. There is nothing to click because there is nowhere to click it: Bambu's anti-abuse layer is challenging your network, and answering a CAPTCHA needs a real browser.

Bambu answers the sign-in with HTTP 418 and a challenge body:

{"captchaId": "...", "error": "We need you to confirm you are not a robot"}

Your email and password are not the problem, and neither is your Bambuddy install. The challenge is keyed to your public IP address, so it applies to every account and every app behind that address, and it normally clears by itself within a few hours. Repeated sign-in attempts extend it -- Bambuddy stops sending sign-in requests for five minutes after seeing a challenge for exactly that reason, so a retry inside that window is refused locally without touching Bambu.

What makes it more likely:

• a VPN, Tailscale exit node, or mobile/CGNAT connection that shares one public address with many users
• a hosting provider or datacenter IP range
• a burst of Bambu Cloud or MakerWorld requests from the same address

To sign in while it lasts, use an access token instead. On the Profiles → Cloud Profiles login form, choose Use access token instead and paste a token from a browser session — the token path does not go through the challenged sign-in endpoint. The same challenge also blocks MakerWorld imports; use Open on MakerWorld and import the 3MF manually until it clears.

Database write contention¶

The SQLite database is hitting database is locked errors under load — common when running several printers at once.

Switch Bambuddy to an external PostgreSQL database. See "Database is locked" Errors and the PostgreSQL guide.

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¶

• GitHub Issues
• GitHub Discussions

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