Odysseus AI Troubleshooting
Last updated: June 3, 2026
Common problems and fixes pulled from GitHub Issues. Each answer is kept short with the exact commands you need.
Default admin password
Odysseus generates a random password on first launch. Find it in the Docker logs.
Tip: Set ADMIN_PASSWORD in your .env file before first run to use your own password.
Port 7000 not responding
The default web UI port. If it doesn't respond, the container may have crashed or another service is using the port.
If the container is not running, restart it:
Tip: Check for port conflicts: lsof -i :7000 (macOS/Linux) or netstat -ano | findstr :7000 (Windows).
Docker Compose errors on startup
Usually a Docker version mismatch, missing GPU overlay, or missing .env file.
Check your Docker Compose version (needs V2):
If you see docker-compose (hyphenated), you have V1. Upgrade to Docker Desktop or install the Compose V2 plugin.
Tip: Copy .env.example to .env if the file is missing.
GPU not detected
Odysseus can't see your GPU inside Docker. You need the right toolkit installed on the host.
NVIDIA: Install the NVIDIA Container Toolkit, then verify:
AMD: Use the ROCm overlay compose file. Apple Silicon: GPU passthrough is not supported in Docker. Use native install instead.
Tip: Make sure you started with the GPU-enabled compose file if one is provided.
Model download fails
Network timeout or insufficient disk space.
Check that the data/ directory exists, is writable, and has enough free space. Large models need 4-40GB each.
ChromaDB errors
Vector database errors, usually disk space or file permission problems.
Check disk space and data directory permissions. If the database is corrupted, you can reset it:
WARNING: -v deletes all volumes including your stored conversations and embeddings. Back up the data/ directory first.
"Not a model" or no models available
Odysseus is a workspace, not an AI model. You need to connect a model backend.
Go to Odysseus Settings and add a model provider. The easiest option is Ollama. For cloud models, try OpenRouter.
Tip: See our Ollama + Models guide for full setup instructions.
Ollama connection refused
Odysseus in Docker can't reach Ollama on the host machine.
Ollama defaults to listening on 127.0.0.1, which Docker containers can't reach. Fix:
In Odysseus settings, use http://host.docker.internal:11434 as the Ollama endpoint (Docker Desktop) or the host IP on Linux.
Memory/RAM issues and OOM crashes
Running out of memory when loading models.
ChromaDB + a model backend is RAM-hungry. Minimum 16GB recommended for local models. If you're running out of memory:
- - Use smaller quantized models (Q4 instead of FP16)
- - Increase Docker memory limit in Docker Desktop settings
- - Close other memory-intensive applications
Tip: Check hardware requirements for recommended specs per model size.
Windows-specific issues
WSL2, Docker Desktop, and path-related problems on Windows.
Windows has its own set of quirks with Docker and WSL2. We have a dedicated guide for this: