Troubleshooting

Common issues and solutions for Aurora

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

2. Ensure all required environment variables are set in .env
3. 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:"

2. 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.
===================================================

3. Add the token to your .env file:

VAULT_TOKEN=hvs.xxxxxxxxxxxxxxxxxxxxxxxxxxxx

4. 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

2. Restart the vault-init container:

docker restart vault-init

3. 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:

   • OpenRouter: https://openrouter.ai/keys
   • OpenAI: https://platform.openai.com/api-keys
   • Anthropic: https://console.anthropic.com/settings/keys

2. Add to .env:

OPENROUTER_API_KEY=sk-or-v1-...
# or
OPENAI_API_KEY=sk-...
# or
ANTHROPIC_API_KEY=sk-ant-...

3. 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

2. Check database logs:

docker logs aurora-postgres-1

3. Verify database credentials in .env match the PostgreSQL configuration

4. 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

2. Try rebuilding:

cd client && npm run build

3. 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

3. 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

2. Access points:

   • File browser: http://localhost:8888
   • Cluster status: http://localhost:9333
   • S3 API: http://localhost:8333

3. 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 [e-mail]

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.