Troubleshooting — PacketPilot Analyze

Docker and Startup

`docker compose up -d` Fails with "Port Already in Use"

Another service is already using one of the required ports: 3000, 8000, 5432, 9000, or 11434.

Find what's using the port:

# Linux
sudo ss -tlnp | grep -E '3000|8000|5432|9000|11434'

# macOS
lsof -i :3000 -i :8000 -i :5432 -i :9000 -i :11434

Fix: Either stop the conflicting service, or change the port mapping in docker-compose.yml for the affected service.

To change the port, edit the ports entry:

services:
  frontend:
    ports:
      - "3001:3000"   # Changed external port from 3000 to 3001

Then restart: docker compose down && docker compose up -d

Services Start But Frontend Shows "502 Bad Gateway"

The backend container may have crashed or may not be ready yet.

Check backend logs:

docker compose logs backend

Wait and retry: The backend takes ~10 seconds to initialize. Refresh the page after waiting.

Restart the backend:

docker compose restart backend

`docker compose up -d` Hangs on "Pulling Ollama Image"

Slow internet connection — the Ollama image is ~2–3 GB. Let it complete.

Monitor pulling progress:

docker compose logs -f ollama

If it fails due to a network timeout, run:

docker compose up -d --pull always

Container Keeps Restarting

Check logs for the crashing container:

docker compose logs <service-name>
# e.g.
docker compose logs backend
docker compose logs postgres

Common causes:

postgres crashing: disk full or corrupted volume. Check with docker compose exec postgres df -h. Try restarting with: docker compose restart postgres
backend crashing: environment misconfiguration. Check .env for missing required variables.
ollama crashing: insufficient memory. Ollama needs at least 4 GB RAM available to Docker.

Ollama and AI

Ollama Fails to Download Model

Check internet connection. Ollama downloads models from https://ollama.ai/library.

If in an air-gapped environment: Download the model on an internet-connected machine, then transfer it:

# On the internet-connected machine:
docker pull ollama/mistral:latest
docker save ollama/mistral:latest > ollama-mistral.tar

# Transfer ollama-mistral.tar to the air-gapped machine, then:
docker load < ollama-mistral.tar

Then set the model in .env:

OLLAMA_MODEL=mistral:latest

And restart:

docker compose restart backend

AI Summaries Return Errors or Are Disabled

Verify AI_SUMMARIES_ENABLED=true in .env
Restart the backend: docker compose restart backend
Test Ollama directly:

curl http://localhost:11434/api/tags

If this returns an empty list or error, Ollama hasn't downloaded the model yet. Pull it:

docker compose exec ollama ollama pull mistral:latest

AI Summaries Are Very Slow

Ollama uses CPU by default. For better performance:

Allocate more CPU cores to the Ollama container in docker-compose.yml:

services:
  ollama:
    deploy:
      resources:
        limits:
          cpus: "4"

Restart the stack:

docker compose down && docker compose up -d

Network and Access

Cannot Access Web UI from Another Machine

By default, the frontend binds to 127.0.0.1 (localhost only). Change the binding in docker-compose.yml:

services:
  frontend:
    ports:
      - "0.0.0.0:3000:3000"

Then restart:

docker compose restart frontend

Reverse Proxy / SSL Termination in Front of Analyze

If placing Analyze behind nginx, Traefik, or another reverse proxy, ensure both ports 3000 (frontend) and 8000 (backend) are proxied, and appropriate headers are set:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-Host $host;
}

location /api {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-Host $host;
}

The frontend and backend must be on the same origin (same protocol, host, and port) for CORS to work correctly.

Database

"Too Many Connections" Error

PostgreSQL has a connection limit. Restart the backend to reset connections:

docker compose restart backend

If the issue persists, the connection limit may need to be increased in the postgres service configuration.

Cases Disappeared or Database Error

Check postgres is running: docker compose ps postgres
Check postgres logs: docker compose logs postgres
If the data volume is corrupted, restore from a backup:

docker compose exec -T postgres psql -U postgres packetpilot < backup_YYYYMMDD.sql

Licensing

"License Invalid" After Entering License Key

The license is bound to the server's hardware ID (MAC address + hostname). If the server's hardware changed significantly, the hardware ID will not match.

Find your current hardware ID in Settings → License in the web UI.

Contact support@db-electronics.no with your license key and hardware ID to have the license re-bound.

"Read-Only Mode" Banner Despite Being Connected to License Server

The grace period may have already expired while the server was unreachable.

Fix:

docker compose restart license-server backend

If the issue persists, contact support.

Collecting Logs for Support

All Container Logs

docker compose logs --tail=100 > packetpilot-logs.txt

Specific Service

docker compose logs --tail=100 backend > backend-logs.txt

Ollama Logs

docker compose logs --tail=100 ollama > ollama-logs.txt

Health Check

Verify all services are healthy:

docker compose ps

All services should show status Up. If any show Exit or Restarting, include those logs when contacting support.

Basic Health Check Commands

# Are all containers running?
docker compose ps

# Is the backend responding?
curl http://localhost:8000/api/health

# Is Ollama responding?
curl http://localhost:11434/api/tags

# Is the license server responding?
curl http://localhost:9000/api/health

# What models are downloaded?
curl -s http://localhost:11434/api/tags | jq '.models[].name'

troubleshooting