Skip to main content

Common Issues

Quick fixes for the most frequently reported problems.

Printer Shows Offline​

A printer appearing offline means O.D.I.N. can't reach it. Work through these checks in order:

  1. Verify the printer's IP address -- make sure the IP configured in O.D.I.N. matches the printer's actual IP. Printers on DHCP may change addresses after a reboot.

  2. Check the access code (Bambu printers) -- Bambu Lab printers require an access code for MQTT authentication. Find it on the printer's screen under Settings > General > Access Code.

  3. Check your firewall -- the Docker container must be able to reach the printer's IP. Common ports:

    • Bambu MQTT: 8883
    • Moonraker/Klipper: 7125
    • PrusaLink: 80
    • Elegoo SDCP: 3000

  4. Check Docker networking -- if your printers are on a different subnet than the Docker host, verify the container can route to that subnet. Test from inside the container:

docker compose exec odin ping 192.168.1.100
tip

If the printer was working before and suddenly went offline, the most common cause is a DHCP IP change. Assign a static IP to your printers to prevent this.

Camera Not Loading​

Camera issues are usually configuration or network related.

  • Verify go2rtc config -- camera streams must be configured in go2rtc. Check the go2rtc admin interface at http://your-server:1984.

  • WebRTC vs RTSP -- WebRTC requires port 8555 (UDP) to be open. If WebRTC fails, the UI falls back to HLS via port 1984 (TCP), which adds a few seconds of latency.

  • Port 8555 firewall -- WebRTC uses UDP on port 8555. Many firewalls block UDP by default. If cameras load slowly (HLS fallback) or not at all, open this port.

  • WebRTC candidate IP -- if running on a remote server, set the webrtc.candidates in go2rtc config to the server's LAN IP, not 127.0.0.1.

AI Detection Not Working​

Vigil AI requires a working camera feed to analyze frames.

  • Camera must be configured -- AI detection runs on go2rtc camera frames. If the camera isn't set up, there's nothing to analyze.

  • Check vision models -- the default ONNX models are copied to /data/vision_models/ on first boot. Verify they exist:

docker compose exec odin ls /data/vision_models/
  • Check detection settings -- make sure AI detection is enabled for the printer in Settings > Vigil AI.

Container Won't Start​

If docker compose up -d fails:

  • Port conflicts -- another service may be using port 8000, 1984, or 8555. Check with:
lsof -i :8000

  • Docker version -- O.D.I.N. requires Docker Engine 20.10+ and Docker Compose v2+. Check with docker --version and docker compose version.

  • Disk space -- the Docker image and data directory need at least 10 GB free. Check with df -h.

  • Permissions -- the odin-data directory must be writable by the container. On Linux, this is usually fine. On macOS, Docker Desktop handles permissions automatically.

Slow Dashboard​

If the dashboard feels sluggish:

  • Number of printers -- large farms (20+ printers) generate more WebSocket traffic. Ensure your server has adequate resources.

  • WebSocket connection -- check that the WebSocket connection is established. Open your browser's developer console and look for WebSocket frames. If the connection keeps reconnecting, there may be a proxy or firewall interfering.

  • Browser console -- check for JavaScript errors in the browser console (F12 > Console tab). Report any errors you see when filing a bug.

warning

If you're running O.D.I.N. behind a reverse proxy (nginx, Caddy, Traefik), make sure WebSocket upgrade headers are passed through. Without this, the dashboard falls back to HTTP polling and feels noticeably slower.