Skip to content

Troubleshooting

Solutions for common issues with BamDude.

Printer states appear slowly when opening the page

Printer cards can display live WebSocket states while the REST status request is still pending. REST supplies additional archive and plate information and remains the fallback when WebSocket access is unavailable. Simultaneous status reads are combined into a bounded batch; returning to a tab refreshes only active queries. A stalled WebSocket viewer is disconnected so it cannot hold up other viewers.

For a support report, note the time you opened the page and attach backend logs covering that time. The following entries help narrow down the delay:

  • WebSocket bootstrap timing: authentication/accept and initial queue preparation, including waits for that viewer's writer to make room in the queue.
  • WebSocket bootstrap applied: the browser has applied the initial states to its query cache. Match the id with the previous entry. client_connect_ms includes the token request, connection and receipt; server_elapsed also includes the return trip for this acknowledgement. Neither measures the first painted card.
  • Slow WebSocket send, WebSocket send timed out, or WebSocket outbox overflow: a browser connection cannot keep up with outgoing data.

Missing acknowledgement alone does not prove a server fault: an older browser bundle, a disconnected tab or a network interruption can also explain it. These timings do not include loading the application's JavaScript or the printer list.

Printer Connection Issues

Printer Won't Connect

Symptoms: Printer shows as disconnected, red indicator.

Solutions:

  1. Verify Developer Mode is enabled
  2. Settings > Network > LAN Only Mode (ON)
  3. Then enable Developer Mode

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

  5. Check IP address

  6. Verify IP in printer network settings

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

  15. Check firewall rules

Connection Drops Frequently

  1. Check WiFi signal strength on the printer card
  2. Network congestion -- Try a dedicated network/VLAN
  3. Router issues -- Restart, check firmware, disable "smart" features
  4. Check BamDude logs: 
    tail -f logs/bamdude.log

A dropped printer now recovers itself

BamDude checks every minute for a printer that was working, has been silent for five minutes, and whose port still answers — and rebuilds the connection itself rather than waiting for the network library to get around to it. One report had a printer offline from 02:19 to 11:24 with the page open the whole time; the old check only ever looked at connections that were still up but had gone quiet, so a fully dropped one fell outside it.

A printer that is simply switched off is left alone, so powering the farm down overnight causes no churn and no log noise. A printer whose connection keeps dying is retried at a growing distance rather than every minute, and the log names how long it was gone.

The printer looks connected and idle, but ignores every command

Symptom. Prints, temperature changes and filament loads are all silently dropped. Uploads appear to succeed, the printer echoes the job back, and then nothing happens — over and over. Status queries still answer, so the printer shows as connected and idle.

Cause. Some firmware (P1 series, 01.08.03 and later) can end up rejecting control commands it cannot verify. The printer reports it the whole time, as HMS 0500-0500-0001-0007 — MQTT command verification failed.

Fix — on the printer:

  1. On the printer's screen, enable Developer Mode (LAN Mode / Developer options, depending on firmware).
  2. Restart the printer.

BamDude now recognises the code, shows it with the same four-group form the printer's own screen displays, and carries that remedy. (Bambu's own advice for this code is to update Bambu Studio or Handy, which is no help for a print sent from BamDude.)

What else changed with it

  • Queueing a print onto such a printer stops on the first attempt and names the cause, instead of spending four and a half minutes and three uploads before failing with an unrelated message about SD cards.
  • The Developer Mode check in the support bundle and printer diagnostics has a third answer, undetermined, rather than treating any reply that was not an outright refusal as a pass.
  • A healthy printer is no longer told to go check its serial number in the moment right after it reconnects.

Camera Issues

Stream Won't Start

  1. Is the printer powered on?
  2. Is camera enabled in printer settings?
  3. Is ffmpeg installed? (included in Docker image)
  4. Is Developer Mode enabled?
  5. Docker users: try network_mode: host

Stream Freezes

  • Check WiFi signal strength
  • Try lowering FPS
  • Use snapshot mode instead

Archiving Issues

Prints Not Being Archived

  1. SD card inserted? Required for file downloads
  2. Developer Mode enabled? Required for FTP access
  3. Auto-archive enabled? Check per-printer setting
  4. Calibration prints are automatically skipped

Queue Issues

Prints Not Starting

  1. Printer connected? Must show green indicator
  2. Plate cleared? Check if "Clear Plate & Start Next" button is showing
  3. Scheduled time? Check if print has a future schedule
  4. Queue Only mode? Check for purple "Staged" badge

Second printer waits a few seconds before starting

Not a bug — but the diagnostic changed. Since c485db1, BamDude's dispatch runs in parallel across printers; only the brief DB-insert phase is wrapped in a startup-lock. The two printers really do receive their jobs simultaneously, and the dispatch toast shows two FTP progress bars side-by-side. The earlier "one job at a time across the whole farm" gate that landed in mid-0.4.1 was scrapped once the startup-lock was in. See Per-Printer Queues → Dispatch behaviour for the full description.

Skip-Objects Button Issues

Skip-objects button is greyed out for OrcaSlicer files

OrcaSlicer ships with both Label objects and Exclude objects off in the print profile, so its 3MFs land in BamDude without the metadata the firmware needs to address individual objects. Bambu Studio enables both by default, so files sliced there work out of the box.

Fix per file:

  1. Print Settings > Others > "Label objects" -- emits the per-object IDs (M624/M625) the firmware needs.
  2. Print Settings > Others > "Exclude objects" -- turns on the slicer-side metadata BamDude reads.
  3. Both must be ticked before slicing. Re-sending an old 3MF without these flags doesn't help -- re-slice with both on, re-upload, and the button lights up.

The flags are stored in the source 3MF's Metadata/project_settings.config; BamDude extracts them on upload (and backfills existing files via migration m022).

Skip-objects button "dies" 5 minutes into a print (old behaviour)

Fixed in 0.4.1, no action needed. Earlier versions periodically swapped the printer's MQTT client for a fresh instance every ~5 minutes, which wiped the in-memory printable_objects state. The button is now repopulated whenever the duplicate-guard branch of on_print_start re-fires, so it stays alive for the whole print. Restart-resilient as well -- printer-started fallback prints get the same treatment via archive_download_retry.

Upgrade-Time Hangs

"Server takes minutes to come up" on first boot after 0.4.1

Migrations m022 and m023 both open every existing 3MF on disk to backfill metadata. m022 extracts the gcode_label_objects / exclude_object flags; m023 extracts the full per-plate breakdown that powers the per-plate gallery in File Manager. Roughly 50-200 ms per file each, and they run sequentially — an install with thousands of archives can spend several minutes inside the migration step before the API responds. Watch for m022 library_files: progress, m022 print_archives: progress, then the matching m023 lines — if they're advancing in batches of 100, the migrations are healthy and just need to finish.

Both are one-shot — subsequent boots skip them via the _migrations table.

Browser console floods with 401s after a long-idle tab

Fixed in dd1d9eb, no action needed on 0.4.1+. Earlier versions waited for a 401 to fire /auth/refresh reactively; when a backgrounded tab returned with five React-Query keys all firing simultaneously, the network panel briefly logged 20–40 401s before the first refresh response unblocked them. The client now decodes the JWT exp claim, schedules a one-shot refresh ~60 s before expiry, and a near-expiry pre-flight check awaits the same coalesced refresh promise. Result: the access token is fresh by the time the visibility-sync invalidates queries, and no 401 leaves the browser. The reactive path stays as a fallback for binary / streaming endpoints.

Docker Issues

Container Won't Start

docker compose logs bamdude

Can't Connect to Printer

docker compose exec bamdude ping YOUR_PRINTER_IP

Try network_mode: host on Linux.

macOS / Windows Docker

Docker Desktop runs containers in a VM. Use port mapping instead of host mode, and add printers manually by IP.

Telegram Bot Issues

Bot Not Responding

  1. Check that the Telegram provider is enabled in Settings > Notifications
  2. Verify the bot token is correct
  3. Check BamDude logs for polling errors
  4. Ensure your chat is authorized

Commands Not Working

  1. Check that your chat has the required permissions
  2. Verify the chat's group assignment in the web UI
  3. Try /start to re-register the chat

Database Issues

Resetting the Database

Data Loss

This deletes all your print history and settings!

docker compose down
# Remove the database file from the data volume
docker compose up -d

Trace IDs in logs

Every HTTP request through BamDude gets a unique trace ID. The same ID is:

  • Echoed in the response as the X-Trace-Id header (so a curl / browser DevTools / log dump can grab it).
  • Attached to every log line that ran during that request — bamdude.log, plus child loggers (bambu_mqtt, print_scheduler, background_dispatch, archive_download_retry, …).
  • Survived across async hops — if a request kicks off a fire-and-forget task (e.g. archive 3MF retry-download), that task's logs still carry the originating request's trace ID.

When reporting an issue, the easiest way to give us the right slice of the log:

  1. Reproduce the problem in your browser. DevTools → Network → click the failing request → Response Headers → copy X-Trace-Id.
  2. Find that ID in bamdude.log: 
    grep <trace-id> logs/bamdude.log
  3. Paste the matched lines into the GitHub issue. That cluster correlates HTTP entry → service work → MQTT / scheduler side effects all in one go, instead of "guess what was happening at 14:32:17 across N components".

The format is short (8 hex chars, [trace=abc12345] in log lines) so log lines stay readable. Trace IDs aren't stable across restarts — they're per-request, not session.

Finding what is slow

A farm that "feels slow" has two very different possible causes, and telling them apart is the whole game: either a database statement is slow, or the server is busy elsewhere and the database is idle. BamDude can measure both. Neither is on by default — leave them off unless you are investigating.

Settings → General:

Setting What it does
Slow query log Writes one warning for every database statement slower than this many milliseconds. 0 turns it off.
Slow request log Writes one warning for every API request slower than this many milliseconds, with its database share. 0 turns it off.

Both take effect the moment you save — no restart — and both work on SQLite and PostgreSQL alike. Reasonable starting points on a busy farm: 500 for queries, 3000 for requests. Turn them back to 0 when you are done.

Reading the request line

slow request 1830ms GET /api/v1/inventory/spools (db 41 queries, 1620ms) [a1b2c3d4]

That trailing [a1b2c3d4] is the trace ID from the section above, so you can pull the whole request's log cluster with one grep. The part in brackets before it is what makes the line worth reading:

  • Most of the time in the database, over many statements (db 41 queries, 1620ms) — the endpoint is asking too often. Usually one query per row where one query for all rows would do.
  • Most of the time in the database, in one or two statements — a missing index, or a query over more rows than it needs. The slow query log names the statement.
  • Almost no time in the database (db 3 queries, 12ms out of 1830 ms) — the database is fine and the server was busy with something else: a big file walk, image work, or simply too much happening at once.

Without turning anything on

Every response already carries a standard Server-Timing header:

Server-Timing: db;dur=1620.4, total;dur=1830.2

Your browser renders it in DevTools → Network → the request → Timing, so the same split is one click away for anything you can reproduce in the UI.

What the log does and does not contain

The slow query log records the text of a statement, shortened and with any credentials in it masked. It never records the values bound to it — those are your file names, spool names and printer serials, and bamdude.log is a file people attach to public issues. Request lines record the method and path only, never the query string.

Self-service diagnostics

BamDude can triage most setup problems for you. On the System page, the Connection Diagnostic section probes each printer (ports, LAN developer mode, Docker network mode, subnet, credentials) and the System Health section scans recent logs against the known-issue catalog below. The in-app bug reporter runs both when you open it, so a fixable problem is surfaced before you file a report. The "How to fix" links on each finding point at the matching section here.

Wrong access code

The printer rejected the file-transfer login. The access code is wrong, or it changed after Developer Mode was toggled. Re-copy the access code from the printer screen (LAN settings) and update it in the printer's settings in BamDude. Note that the serial number is case-sensitive — BamDude now uppercases it for you on save.

FTPS port 990 blocked

BamDude could not reach the printer's file-transfer port (FTPS 990). The port is blocked, or the printer is off or on another subnet. Make sure nothing (firewall, Docker bridge networking) blocks port 990 between BamDude and the printer, and that both are on the same network.

FTPS TLS failure

The TLS handshake with the printer's file-transfer server failed — often a firewall/proxy intercepting the connection, or outdated printer firmware. Update the printer firmware and check that nothing intercepts port 990.

MQTT connection unstable

The control connection (MQTT 8883) repeatedly disconnects and reconnects — usually a weak network path 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.

Camera RTSPS port 322

The live camera could not be reached on port RTSPS 322. The port is blocked, or the camera / LAN liveview is off on the printer. Enable the camera and LAN liveview on the printer and make sure port 322 is not blocked. This does not affect printing.

Store sent files on external storage

BamDude read the printer's own report of the Store sent files on external storage setting (install step 4) and found it turned off. Without it, the printer never keeps the sliced .gcode.3mf, so every archived print is missing its thumbnail and slicer metadata. Turn the setting on in the slicer so each job is stored on the printer. Note that on some older firmware/slicer combinations this is a slicer-only preference the printer never reports back — the diagnostic can't see that variant, but the Archives page shows a banner when prints arrive without thumbnails.

On some models this check is skipped rather than failed: the P1P, P1S, A2L and X1E have an SD card slot but no reachable way to turn the option on — they never report support for it, so Bambu Studio / OrcaSlicer don't draw the toggle, and the P1-series has no screen to set it from. Because there is nothing to fix, the diagnostic explains that instead of showing a permanent failure. If a firmware update starts exposing the option, the check re-enables itself automatically.

Printer is publishing status

The MQTT broker accepted the connection, but no status reports arrived from the printer. The broker accepts a connection even when the serial number is wrong or mis-cased — the printer's report topic is case-sensitive — so control looks connected while the slicer side shows empty AMS, no filaments, and no K-profiles. The diagnostic waits up to 10 seconds for the printer's first status report, showing a live elapsed-seconds counter so the wait doesn't look hung. If it fails, re-check the serial number for typos and case (BamDude now uppercases it on save) and confirm the printer is powered on and reachable.

Database is locked

The SQLite database is hitting "database is locked" errors under load — common when running several printers at once. Switch BamDude to an external PostgreSQL database (see the PostgreSQL guide).

Getting Help

When reporting issues, include:

  • BamDude version
  • Printer model and firmware version
  • Operating system
  • Steps to reproduce
  • Error messages from logs
  • Docker compose configuration (if applicable)

File issues at github.com/kainpl/bamdude/issues.

Originally based on Bambuddy documentation.