Troubleshooting

Troubleshooting

This page collects the most common problems and how to fix them. For protocol- and architecture-level reference, see Protocol Details and Architecture.

First-line checks

./ankerctl.py config show         # account configured? printer present?
./ankerctl.py mqtt monitor        # MQTT cloud connectivity (Ctrl-C after a few events)
./ankerctl.py pppp lan-search     # LAN discovery (printer must appear within ~5s)
curl http://localhost:4470/api/health   # web server alive?

If any of these fails, jump to the relevant section below.

Connection issues

Printer not found on LAN

Symptoms: pppp lan-search returns nothing, no video stream, file uploads fail.

Causes (most common first):

1. Firewall blocking UDP 32108. On Linux with ufw, run:

   sudo ufw allow in proto udp to any port 32108

   See Firewall ufw for the full background.

2. Different subnet / VLAN. PPPP discovery uses a UDP broadcast — broadcasts do not cross routers. Put ankerctl and the printer on the same L2 segment.

3. Wi-Fi client isolation. Some access points (especially "Guest Network" SSIDs) block client-to-client traffic. Disable AP isolation or move both devices onto the main SSID.

4. Docker bridge networking. You must use network_mode: host in docker-compose.yaml. Bridge networking blocks UDP broadcasts. macOS and Windows hosts cannot use host networking — fall back to the Python install.

5. Printer in sleep mode. Wake it via the touchscreen and retry within a few seconds.

6. Wrong printer selected. If multiple printers are configured, check PRINTER_INDEX or use the printer selector in the navbar.

MQTT connection fails

Symptoms: No print status updates in the UI, cannot send G-code, dashboard shows no temperatures.

1. Config not imported. Open Setup → Account and either upload login.json, click Import From eufyMake Studio, or sign in directly.

2. auth_token expired. Re-import the cache or re-run config login. Tokens expire after extended periods; the symptom is usually a clean disconnect followed by no reconnect.

3. Outbound port blocked. MQTT connects to Anker's cloud broker on TCP 8789 (TLS). Verify your firewall allows outbound 8789.

4. Region mismatch. If your account moved regions (US ↔ EU), re-run config login so ankerctl re-detects the closest API server.

5. Self-hosted broker without CA pin. If you switched to the offline / Mosquitto stack, you must point ankerctl at the local CA:

   ./ankerctl.py --mqtt-ca-cert /path/to/ca.crt mqtt monitor
   # or via env var
   ANKERCTL_MQTT_CA_CERT=/path/to/ca.crt

Web UI issues

Cannot reach the web UI

1. Bind address. Default is 127.0.0.1. For Docker or remote access, set FLASK_HOST=0.0.0.0.

2. Port conflict. Default port is 4470. Check:

   ss -tlnp | grep 4470
   lsof -i :4470

3. Host firewall (TCP). Allow the web port:

   sudo ufw allow in proto tcp to any port 4470

401 Unauthorized

1. API key configured but not provided. Append ?apikey=<key> to any URL once — a session cookie is set automatically.
2. Session expired. Clear cookies and re-bootstrap with ?apikey=<key>.
3. Wrong key. Keys are case-sensitive. Verify with ./ankerctl.py config show. Env var ANKERCTL_API_KEY takes precedence over the value in default.json.

Video stream does not load

1. PPPP not connected. Check the PPPP status dot in the navbar. If yellow → the IP is a stale fallback. If red → discovery failed (see "Printer not found on LAN" above).

2. Browser codec. The stream is raw H.264 NAL units rendered with jMuxer. Chrome and Firefox work best. Safari and embedded browsers may struggle.

3. Stall detection. No frame for 5 s triggers a soft restart; 3 consecutive failures raises ServiceRestartSignal and recreates the video service. Reload the page after a stall.

4. videoqueue not started. Confirm with GET /api/debug/services (when ANKERCTL_DEV_MODE=true).

Setup banner is red on import

The error message displayed in the red banner is the actual upstream error. Common cases:

• "eufyMake Studio not running" — the LevelDB is locked while the slicer is closed. Open and sign into the slicer, then retry.
• "Login failed: invalid credentials" — re-check email/password. Try the country code that matches your account region.
• "CAPTCHA required" — solve the inline CAPTCHA and retry.

Print issues

Upload fails or times out

1. File too large. Increase UPLOAD_MAX_MB (default 2048).
2. PPPP not connected. File transfer uses PPPP. See "Printer not found on LAN".
3. Upload rate too high. On congested Wi-Fi, lower UPLOAD_RATE_MBPS to 5. Raise to 25 or 50 only on stable wired networks.

Print does not start after upload

1. "Send and Print" semantics. ankerctl uploads and immediately starts. There is no upload queue on the printer.
2. Printer busy. A print is already running. Pause or cancel it first.
3. Touchscreen conflict. If someone is interacting with the touchscreen at the moment of the start, the printer can ignore the start command. Retry.

G-code rejected or behaves oddly

1. Slicer compatibility. Use PrusaSlicer, OrcaSlicer, SuperSlicer, or Bambu Studio. Other slicers may emit commands the Anker firmware does not understand (e.g. M115, M119, M503 are stripped from the Anker Marlin fork).
2. File encoding. Use UTF-8 with LF line endings. CRLF can break the slicer-header parser used to extract layer counts.
3. Anker-removed commands. See Protocol Details → Firmware notes for the full list of disabled G-codes.

Layer count shows wrong total

The printer reports layer counts based on Z-moves, which differs from slicer-declared totals when variable layer height is used. ankerctl extracts ;LAYER_COUNT:N (Orca), ; total layer number: N (Bambu), or counts ;LAYER_CHANGE (Prusa) from the G-code header at upload time. If the slicer omits these markers, the printer's count is shown instead.

Timelapse issues

Timelapse not recording

1. Feature disabled. Set TIMELAPSE_ENABLED=true (env var or Setup → Timelapse).
2. ffmpeg not installed. Required for video assembly. Verify with ffmpeg -version. Docker images ship with it; for Python installs, install separately (apt install ffmpeg, brew install ffmpeg).
3. No active print. Capture only runs during prints — it auto-starts on ct=1000 value=1 and assembles on ct=1000 value=0.

Timelapse video is empty or very short

1. Camera unavailable. If PPPP is disconnected during the capture, no frames are saved.
2. Interval too long. For a 10-minute print at the default 30 s interval, you get ~20 frames. Reduce TIMELAPSE_INTERVAL_SEC.
3. Resume window. A paused-and-resumed print appends to the same timelapse only if resumed within 60 minutes. Beyond that, a new capture starts.

Timelapse light not toggling

TIMELAPSE_LIGHT controls the printer LED:

• snapshot — light on, wait 1.5 s, shoot, wait 1 s, light off (per frame)
• session — light on at capture start, off at finish
• (unset) — do not touch the light

Verify the value in Setup → Timelapse or via ./ankerctl.py config show.

Notification issues

Apprise notifications not arriving

1. Apprise server unreachable. APPRISE_SERVER_URL must point to a running Apprise API server (the Docker image is caronc/apprise-api).
2. Wrong key. APPRISE_KEY must match the key configured in your Apprise server.
3. Event disabled. Each event has its own toggle: APPRISE_EVENT_PRINT_STARTED, APPRISE_EVENT_PRINT_FINISHED, APPRISE_EVENT_PRINT_FAILED, APPRISE_EVENT_GCODE_UPLOADED, APPRISE_EVENT_PRINT_PROGRESS.
4. Test first. Use Setup → Notifications → Send test to isolate the connection.

Snapshots not attached

1. Live snapshot failed. The Apprise notifier asks VideoQueue for a frame; if PPPP is down, it falls back to the G-code preview when APPRISE_SNAPSHOT_FALLBACK=true.
2. No G-code preview. Some slicers do not emit a thumbnail. Enable thumbnail export in your slicer settings.
3. Quality mismatch. APPRISE_SNAPSHOT_QUALITY=fhd requires the printer to be in snapshot mode (FHD is not used for live streaming).

Home Assistant issues

Entities not appearing

1. MQTT broker. Set HA_MQTT_HOST and HA_MQTT_PORT to your broker (Mosquitto, EMQX, etc.). Verify with mosquitto_sub -h <host> -t '#' -v.
2. Discovery prefix. Default homeassistant. If you customized HA's prefix, set HA_MQTT_DISCOVERY_PREFIX to match.
3. Restart HA. After the first publish, restart Home Assistant to pick up the discovery payloads.
4. MQTT integration. The HA MQTT integration must be installed and configured.

Camera entity is missing for the second printer

Multi-printer Camera-Discovery is currently incomplete: HA registers only one camera (the active printer). For 2+ printers, the second camera is not auto-registered. This is a known limitation — see the issue tracker for status.

Light switch does not toggle the printer

1. MqttQueue not connected. The light command goes via PPPP, which requires a healthy LAN session. Check the PPPP status dot.
2. Topic mismatch. Verify in HA that the Printer Light switch publishes on <HA_MQTT_TOPIC_PREFIX>/<printer_sn>/light/set.

Docker issues

Container restarts in a loop

1. Logs first: docker logs ankerctl (or docker compose logs -f ankerctl).
2. Health check mismatch. The bundled HEALTHCHECK curls 127.0.0.1:4470. If you set FLASK_HOST to a specific non-loopback IP that is not also reachable as 127.0.0.1, the check fails. Use FLASK_HOST=0.0.0.0 (or unset).
3. Volume permissions. The container runs as UID 1000 by default. If your host config dir is owned by a different user, the entrypoint cannot write default.json. Rebuild with --build-arg UID=$(id -u) --build-arg GID=$(id -g) or chown -R 1000:1000 ~/.config/ankerctl.

Permission denied on /home/ankerctl/.config/ankerctl

sudo chown -R 1000:1000 ~/.config/ankerctl/
# or rebuild with matching UID/GID
docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) -t ankerctl:local .

SELinux blocking the volume mount

Add :z to the mount: -v ~/.config/ankerctl:/home/ankerctl/.config/ankerctl:z.

Multi-printer issues

Cannot switch active printer

1. Print active. Switching is blocked during a print and returns 409. Wait for the print to finish, or cancel it first.
2. PRINTER_INDEX env var locked. When set, the navbar dropdown is disabled and POST /api/printers/active returns 403. Unset the env var and restart.

Wrong printer answers

If you have two printers with the same alias, lan-search may return them in arbitrary order. Use the DUID (not the alias) to identify which one you want and set PRINTER_INDEX accordingly.

Debug mode

For deep inspection set ANKERCTL_DEV_MODE=true and restart. Then:

• Debug tab in the UI exposes State Inspector, Simulation, Service health, Log Viewer
• All /api/debug/* endpoints become available (auth required if ANKERCTL_API_KEY is set)
• /api/debug/services lists every service with state, refcount, and last error

Warning Do not enable in production. The Debug tab exposes internal state and lets you inject synthetic events.

Log files

Set ANKERCTL_LOG_DIR to enable per-component log files:

ANKERCTL_LOG_DIR=/var/log/ankerctl ./ankerctl.py webserver run

Files written:

File	Source
ankerctl.log	Root logger + stdout mirror
mqtt.log	MQTT cloud client
web.log	Flask requests + WebSocket events
history.log	PrintHistory
timelapse.log	TimelapseService
homeassistant.log	HomeAssistantService
bed_leveling/YYYYMMDD_HHMMSS.bed	Saved bed grid snapshots

In Docker, the standard mount path is /logs. View files via the Debug tab → Log Viewer (when ANKERCTL_DEV_MODE=true) or directly on disk.

Getting help

Before opening an issue, please collect:

1. Version: git rev-parse --short HEAD or the Docker image tag
2. Printer model and firmware: firmware is queryable with ./ankerctl.py mqtt send ZZ_MQTT_CMD_FIRMWARE_VERSION
3. Log excerpt: the last ~200 lines of ankerctl.log (redact auth_token, mqtt_key, email)
4. Repro steps: the exact CLI / UI sequence that triggers the issue

Open at https://github.com/Django1982/ankermake-m5-protocol/issues.