Skip to main content

Common Issues

Start with Guided diagnostics to check the server, printer and file transfer, then use the relevant checks below.

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.

  • Check the saved camera configuration -- use ODIN's printer and camera settings. The internal go2rtc API on port 1984 is not a public admin page; do not expose it.

  • Camera media path -- allow WebRTC media on port 8555 TCP/UDP where needed. Camera API and HLS requests use ODIN's authenticated routes, not a public port 1984.

  • 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 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. See the section below.

WebSocket Behind a Reverse Proxy​

O.D.I.N. uses WebSocket connections (ws://host:8000/ws) for real-time dashboard updates. Reverse proxies must explicitly forward WebSocket upgrade requests, or the connection will fail silently and the dashboard will fall back to slow HTTP polling.

Nginx Proxy Manager (NPM)​

NPM does not forward WebSocket upgrades by default when using the "Proxy Host" UI.

Fix: In the NPM proxy host settings, go to the Advanced tab and add:

location /ws {
    proxy_pass http://<container-ip>:8000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400;
}
Use the Container IP, Not localhost

NPM runs inside its own Docker container. localhost inside NPM resolves to the NPM container itself, not your host machine. Use the O.D.I.N. container's IP address or Docker service name (e.g., odin:8000 if on the same Docker network) in the proxy_pass directive.

Cloudflare Tunnel​

Cloudflare Tunnels forward WebSocket connections natively — no additional configuration is needed. WebSocket support is enabled by default for all tunneled origins.

Ensure your tunnel's public hostname points to http://odin:8000 (or wherever O.D.I.N. is running). Both the HTTP API and WebSocket traffic will flow through the same tunnel.

Generic Nginx Configuration​

If you are running nginx directly (not NPM), add the WebSocket upgrade headers to your server block:

server {
    listen 443 ssl;
    server_name odin.example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;
    }
}

The proxy_read_timeout 86400 (24 hours) prevents nginx from closing idle WebSocket connections prematurely. The default 60-second timeout will cause frequent reconnects.

Caddy​

Caddy forwards WebSocket connections automatically. No special configuration is needed:

odin.example.com {
    reverse_proxy localhost:8000
}

Traefik​

Traefik also forwards WebSocket connections automatically via its standard loadBalancer configuration. No additional middleware is required.

See Also​