Troubleshooting & FAQ Guide

Troubleshooting guide addressing common setup, operational, and runtime issues.

Common Issues & Solutions

ValueError: Fernet key must be 32 url-safe base64-encoded bytes.

Cause: Missing or invalid
```
FERNET_KEY
```
in environment (
```
.env
```
).

Solution: Run

python scripts/generate_fernet_key.py --write-env

to generate and save a valid 32-byte key into

services/api/.env

django.db.utils.OperationalError: Ident authentication failed for user "metapilot"

Cause:
```
DATABASE_URL
```
is set to PostgreSQL in
```
.env
```
, but local PostgreSQL is not running.
Solution: Leave
```
DATABASE_URL=
```
blank in
```
services/api/.env
```
to use the local SQLite database (
```
db.sqlite3
```
).

redis.exceptions.TimeoutError: Timeout reading from localhost:6379

Cause: Redis server is stopped or Channel Layer connection timed out.
Solution: Ensure Redis is running (
```
redis-cli ping
```
->
```
PONG
```
). Restart Daphne backend server (
```
./scripts/backend.sh
```
).

Cause: Worker processes stopped or wrong Redis database index targeted.
Solution: Verify Celery worker daemon is running (
```
celery -A core inspect active
```
).