Skip to main content

​
Common Setup Issues

​
Docker and Docker Compose

​
Docker Compose version error

Problem: Error messages about incompatible Docker Compose version. Solution: Ensure you have Docker Compose version 28.x or higher: 
docker compose version
If your version is older, update Docker Desktop or install the latest Docker Compose.

​
Port conflicts

Problem: Aurora fails to start with port binding errors. Solution: Check if another application is using these ports:
  • 3000: Frontend (Next.js)
  • 5080: API server (Flask)
  • 5006: Chatbot WebSocket
  • 5432: PostgreSQL
  • 6379: Redis
  • 8080: Weaviate
  • 8200: Vault
  • 8333: SeaweedFS S3 API
  • 9333: SeaweedFS cluster status
To find and stop conflicting processes: 
# Find process using port 3000
lsof -i :3000

# Kill the process (replace PID with actual process ID)
kill -9 PID

​
Container fails to start

Problem: One or more containers exit immediately after starting. Solution:
  1. Check container logs:
make logs

# Or check specific container
docker logs aurora-server-1
docker logs aurora-frontend-1
  1. Ensure all required environment variables are set in .env
  2. Try rebuilding containers:
make down
make dev-build
make dev

​
Vault Initialization Issues

​
Missing Vault token

Problem: Aurora services cannot connect to Vault, or you see authentication errors. Solution: The Vault token must be set in your .env file.
  1. Get the root token from vault-init logs:
docker logs vault-init 2>&1 | grep "Root Token:"
  1. You’ll see output like:
===================================================
Vault initialization complete!
Root Token: hvs.xxxxxxxxxxxxxxxxxxxxxxxxxxxx
IMPORTANT: Set VAULT_TOKEN=hvs.xxxxxxxxxxxxxxxxxxxxxxxxxxxx in your .env file
           to connect Aurora services to Vault.
===================================================
  1. Add the token to your .env file:
VAULT_TOKEN=hvs.xxxxxxxxxxxxxxxxxxxxxxxxxxxx
  1. Restart Aurora:
make down
make dev  # or make prod-prebuilt

​
Vault sealed state

Problem: Vault is sealed and services cannot access secrets. Solution: The vault-init container automatically unseals Vault on startup. If Vault is sealed:
  1. Check vault-init container status:
docker ps -a | grep vault-init
  1. Restart the vault-init container:
docker restart vault-init
  1. If issues persist, restart the entire stack:
make down
make dev

​
Lost Vault data

Problem: Vault data disappeared after restart. Solution: Vault data is persisted in Docker volumes (vault-data, vault-init). Check if volumes exist: 
docker volume ls | grep vault
If volumes are missing, they may have been removed with docker volume prune. Unfortunately, this data cannot be recovered. You’ll need to reinitialize: 
make down
make init
make dev

​
Configuration Issues

​
Missing LLM API key

Problem: Aurora cannot process queries due to missing LLM configuration. Solution: Add an LLM API key to your .env file:
  1. Get an API key from:
  2. Add to .env: 
OPENROUTER_API_KEY=sk-or-v1-...
# or
OPENAI_API_KEY=sk-...
# or
ANTHROPIC_API_KEY=sk-ant-...
  1. Restart Aurora:
make down
make dev

​
Cloud connector issues

Problem: Aurora cannot connect to cloud providers (GCP, AWS, Azure). Solution: Cloud connectors are optional. Add provider credentials only if you need cloud integration:
  1. Check .env.example for required variables
  2. For GCP: Place service account JSON in server/connectors/gcp_connector/*.json
  3. For AWS: Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
  4. For Azure: Set Azure-specific credentials
Note: Aurora works without cloud provider accounts. The LLM API key is the only required external dependency.

​
Development Issues

​
Hot reload not working

Problem: Code changes don’t reflect in running containers. Solution: For frontend changes: 
# Frontend has hot reload in dev mode
# Just save your changes and refresh browser
For backend changes: 
# Rebuild the server
make rebuild-server
Or restart in development mode: 
make down
make dev

​
Database connection errors

Problem: Aurora cannot connect to PostgreSQL. Solution:
  1. Verify PostgreSQL container is running:
docker ps | grep postgres
  1. Check database logs:
docker logs aurora-postgres-1
  1. Verify database credentials in .env match the PostgreSQL configuration
  2. Restart the stack: 
make down
make dev

​
Frontend build errors

Problem: Frontend fails to build or compile. Solution:
  1. Check for linting errors:
cd client && npm run lint
  1. Try rebuilding:
cd client && npm run build
  1. Clear Next.js cache:
cd client
rm -rf .next
npm run build

​
Deployment Issues

​
Production build fails

Problem: make prod-local or make prod-prebuilt fails. Solution:
  1. Ensure all required environment variables are set
  2. Check Docker logs for specific errors:
make logs
  1. Try cleaning up and rebuilding:
make down
docker system prune -f
make prod-local

​
Cannot pull prebuilt images

Problem: make prod-prebuilt fails to pull images from GHCR. Solution:
  1. Check your internet connection
  2. Verify the version exists at https://github.com/orgs/Arvo-AI/packages
  3. Build from source instead:
make prod-local

​
Version pinning

Problem: Want to use a specific Aurora version. Solution: Pin a specific release: 
make prod-prebuilt VERSION=v1.2.3
Available versions are listed at https://github.com/orgs/Arvo-AI/packages.

​
Storage Issues

​
SeaweedFS not accessible

Problem: Cannot access SeaweedFS UI or S3 API. Solution:
  1. Verify SeaweedFS container is running:
docker ps | grep seaweedfs
  1. Access points:
  2. Default credentials: admin / admin

​
Object storage connection errors

Problem: Aurora cannot store or retrieve files. Solution:
  1. Check storage configuration in .env
  2. Verify SeaweedFS is running and accessible
  3. Check Aurora server logs:
docker logs -f aurora-server-1

​
Getting Help

If you’re still experiencing issues:
  1. Check the FAQ for common questions
  2. Search existing GitHub issues
  3. Review the support options
  4. Contact the team at [email protected]

​
Reporting Bugs

When reporting bugs, include:
  • Clear description of the issue
  • Steps to reproduce
  • Expected vs actual behavior
  • Environment details (OS, Docker version, browser)
  • Relevant configuration from .env (redact secrets)
  • Error logs from make logs
  • Screenshots if applicable
See the Contributing Guide for more details on bug reporting.

Build docs developers (and LLMs) love

Get started for freeTalk to us