> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Arvo-AI/aurora/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
VAULT_TOKEN=hvs.xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

4. Restart Aurora:

```bash theme={null}
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:

```bash theme={null}
docker ps -a | grep vault-init
```

2. Restart the vault-init container:

```bash theme={null}
docker restart vault-init
```

3. If issues persist, restart the entire stack:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](https://openrouter.ai/keys)
   * OpenAI: [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)
   * Anthropic: [https://console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)

2. Add to `.env`:

```bash theme={null}
OPENROUTER_API_KEY=sk-or-v1-...
# or
OPENAI_API_KEY=sk-...
# or
ANTHROPIC_API_KEY=sk-ant-...
```

3. Restart Aurora:

```bash theme={null}
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:

```bash theme={null}
# Frontend has hot reload in dev mode
# Just save your changes and refresh browser
```

For backend changes:

```bash theme={null}
# Rebuild the server
make rebuild-server
```

Or restart in development mode:

```bash theme={null}
make down
make dev
```

### Database connection errors

**Problem**: Aurora cannot connect to PostgreSQL.

**Solution**:

1. Verify PostgreSQL container is running:

```bash theme={null}
docker ps | grep postgres
```

2. Check database logs:

```bash theme={null}
docker logs aurora-postgres-1
```

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

4. Restart the stack:

```bash theme={null}
make down
make dev
```

### Frontend build errors

**Problem**: Frontend fails to build or compile.

**Solution**:

1. Check for linting errors:

```bash theme={null}
cd client && npm run lint
```

2. Try rebuilding:

```bash theme={null}
cd client && npm run build
```

3. Clear Next.js cache:

```bash theme={null}
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:

```bash theme={null}
make logs
```

3. Try cleaning up and rebuilding:

```bash theme={null}
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](https://github.com/orgs/Arvo-AI/packages)
3. Build from source instead:

```bash theme={null}
make prod-local
```

### Version pinning

**Problem**: Want to use a specific Aurora version.

**Solution**: Pin a specific release:

```bash theme={null}
make prod-prebuilt VERSION=v1.2.3
```

Available versions are listed at [https://github.com/orgs/Arvo-AI/packages](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:

```bash theme={null}
docker ps | grep seaweedfs
```

2. Access points:
   * File browser: [http://localhost:8888](http://localhost:8888)
   * Cluster status: [http://localhost:9333](http://localhost:9333)
   * S3 API: [http://localhost:8333](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:

```bash theme={null}
docker logs -f aurora-server-1
```

## Getting Help

If you're still experiencing issues:

1. Check the [FAQ](/help/faq) for common questions
2. Search existing [GitHub issues](https://github.com/Arvo-AI/aurora/issues)
3. Review the [support options](/help/support)
4. Contact the team at [info@arvoai.ca](mailto:info@arvoai.ca)

## 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](https://github.com/Arvo-AI/aurora/blob/main/CONTRIBUTING.md) for more details on bug reporting.