Skip to main content

Common Issues

Port Already in Use​

Symptom: docker compose up -d fails with an error like Bind for 0.0.0.0:3000 failed: port is already allocated.

Solution:

  1. Identify which process is using the port: 
    lsof -i :3000
  2. Either stop the conflicting process, or change the port used by RAG-DocBot by setting DOCKER_PORT in .env to an available port, then re-run docker compose up -d.

Backend Fails to Start / Database Migration Error​

Symptom: The backend container exits immediately. Logs show a database connection error or migration failure.

Solution:

  1. Check the backend logs: 
    docker compose logs backend
  2. Ensure the postgres service is healthy before the backend starts: 
    docker compose ps
  3. If postgres is not running, start it explicitly and wait for it to become healthy: 
    docker compose up -d postgres
    docker compose logs -f postgres
  4. Once postgres is healthy, start the backend: 
    docker compose up -d backend

License Key Rejected​

Symptom: The UI shows a license error, or POST /api/license returns a 400 or 422 error.

Solution:

  1. Verify the license.key file is in the same directory as docker-compose.yml.
  2. Ensure the file content has not been truncated or modified (e.g. by a text editor adding a trailing newline or changing encoding).
  3. Contact your vendor if the key continues to be rejected — the key may be expired or issued for a different host.

Cannot Pull Images (Authentication Error)​

Symptom: docker compose pull fails with unauthorized: authentication required or similar.

Solution:

  1. Log in to the private container registry with your vendor-provided credentials: 
    docker login <registry-url>
  2. Enter your registry username and token/password when prompted.
  3. Retry docker compose pull.

If your credentials have expired, contact your vendor for a new token.

Inference Service Keeps Restarting​

Symptom: docker compose ps shows the inference service in a restart loop. Logs show a model loading error.

Solution:

  1. Check the inference logs: 
    docker compose logs inference
  2. Verify the model file exists and is named correctly: 
    ls -lh ./models/modelfile.gguf
  3. Common causes:
    • The model file is missing or has the wrong name — it must be modelfile.gguf.
    • The model requires more RAM than is available. Try a smaller or more heavily quantised variant (e.g. Q4_K_M instead of Q8_0).
    • The model file is corrupted — re-download it from the source.
  4. After fixing the issue, restart the inference service: 
    docker compose up -d inference