Troubleshooting FAQ

The shortcuts and fixes for the issues that come up most often. If yours isn't here, open an issue on GitHub or ping the Discord community.

First — basic diagnostics

Before anything else, capture the state of the stack:

docker compose ps              # are all services up + healthy?
docker compose logs --tail=200 # recent logs from every service
docker compose logs django     # focused log for one service

"unhealthy" or "exited" containers are almost always the culprit — start there.

Port conflicts

Port 80 already in use

You'll see this when starting the stack:

Error response from daemon: failed to bind host port for 0.0.0.0:80:
listen tcp 0.0.0.0:80: bind: address already in use

Another web server is bound to port 80 (Apache, nginx, IIS, an existing Caddy). Either stop it or remap Caddy. Edit docker-compose.yml:

services:
  caddy:
    ports:
      - "8080:80"

Restart and visit http://local-ai.localhost:8080.

Port 5433 / 11434 / 8501 conflicts

Same fix — change the host side of the mapping:

Find what's holding a port

sudo lsof -iTCP:80 -sTCP:LISTEN

netstat -ano | findstr :80

Docker won't start the stack

"Cannot connect to the Docker daemon"

Docker isn't running. Start Docker Desktop (macOS / Windows) or:

sudo systemctl start docker     # Linux with systemd
docker info                     # should now succeed

"docker-compose: command not found" or v1 errors

This project requires Docker Compose v2 (invoked as docker compose, two words). Check:

docker compose version

Upgrade Docker Desktop or install the docker-compose-plugin package on Linux.

"environment variable not set" warnings

You're missing the .env file at the project root. Copy it from the template:

cp .env.example .env
docker compose up -d

GPU not detected

By default, Ollama runs CPU-only inside Docker. To use a GPU you need to expose it to the container.

Linux + NVIDIA

1. Install the NVIDIA Container Toolkit on the host.
2. Edit docker-compose.yml and add a deploy block to the ollama service:

ollama:
  image: ollama/ollama:latest
  deploy:
    resources:
      reservations:
        devices:
          - driver: nvidia
            count: all
            capabilities: [gpu]

Verify after restart:

docker compose exec ollama nvidia-smi

macOS (Apple Silicon)

Docker Desktop does not expose the Apple Neural Engine or Metal GPU to containers. For maximum performance on a Mac, install Ollama on the host and point the stack at it — see Use host Ollama in Configuration.

Windows + NVIDIA (WSL2)

Install the latest NVIDIA drivers for Windows. Inside WSL2 install the CUDA-enabled Docker plumbing, then use the same deploy block as Linux.

Disk space

The installer warned about low disk space

Reclaim space without losing your data:

# remove dangling images, build cache, stopped containers
docker system prune -a

# remove only old image layers
docker image prune -a

Do not run docker volume prune — that deletes Postgres data, Ollama models, and Whisper models.

Models eating disk

See what Ollama has cached:

docker compose exec ollama ollama list

Remove specific models you no longer use:

docker compose exec ollama ollama rm llama3.1:70b

Where Docker stores data

Large file uploads fail

By default the request body limit is moderate. If a big PDF / DOCX upload returns 413 Payload Too Large or 504, raise it in two places.

1. Caddy

Edit Caddyfile and add a request_body directive:

api.local-ai.localhost {
    reverse_proxy django:8000
    request_body {
        max_size 200MB
    }
}

2. Django

Django enforces its own upload limit. Set these in .env (read by the Django settings file):

DATA_UPLOAD_MAX_MEMORY_SIZE=209715200
FILE_UPLOAD_MAX_MEMORY_SIZE=209715200

200 MB shown above. Restart Caddy and Django:

docker compose up -d --force-recreate caddy django

"local-ai.localhost" won't resolve

macOS and most modern Linux distros resolve .localhost to 127.0.0.1 automatically (RFC 6761). On Windows and minimal Linux setups, you must add a hosts entry:

echo "127.0.0.1 local-ai.localhost api.local-ai.localhost" | sudo tee -a /etc/hosts

1. Open Notepad as Administrator
2. File → Open → C:\Windows\System32\drivers\etc\hosts
3. Add line:
   127.0.0.1 local-ai.localhost api.local-ai.localhost
4. Save

Ollama / model errors

"model not found"

The app references a model that isn't pulled. List installed models and pull what's missing:

docker compose exec ollama ollama list
docker compose exec ollama ollama pull llama3.1:8b

Ollama container stuck or out of memory

Large models can exceed available RAM. Either switch to a smaller model (llama3.2:3b, phi3:mini) or raise Docker Desktop's memory allocation to 12–16 GB.

First reply is very slow

That's the model loading into memory. Subsequent prompts are fast. Keep the chat tab open to keep the model warm.

RAG / document chat errors

"401 Unauthorized" from the RAG service

RAG_API_KEY is mismatched. The same value must appear in .env for Django, Next.js, and the RAG container. After fixing:

docker compose up -d --force-recreate django nextjs rag

Answers contain no citations

The embedding model is missing. Pull it explicitly:

docker compose exec ollama ollama pull nomic-embed-text

Whisper / speech-to-text errors

Transcription is very slow

You're using a too-large model for the host CPU. Switch to tiny or base.en in .env:

WHISPER_MODEL=base.en

Then restart: docker compose up -d --force-recreate whisper.

Wrong language detected

The .en variants are English-only. For multilingual audio use the plain variants (tiny, base, small).

Updater issues

"Install Update" never completes

The updater needs access to the host Docker socket and the project directory. Confirm both are mounted:

docker compose config | grep -A 8 'updater:'

You should see /var/run/docker.sock and the project root bind-mounted into /project. If they're missing, the volume mounts have been removed from docker-compose.yml.

Updater fails on Linux with permission denied

The container's user can't access the host Docker socket. Add the container's user to the host's docker group, or run the updater as root (which the stack does by default).

Reset everything (last resort)

This deletes all data — users, chats, indexed documents, Ollama models, Whisper cache. Use only when you want a clean re-install.

docker compose down -v
docker compose up -d --build

Then re-run database migrations and re-pull Ollama models — see Getting Started.

Still stuck?