Troubleshooting¶

Solutions to common issues

Authentication Issues¶

403 Forbidden - Missing API Key¶

Symptoms:

{
  "detail": "Forbidden"
}

Cause: Missing or invalid X-API-Key header

Solution:

# Ensure API key header is included
curl -H "X-API-Key: your-secret-key-here" ...

# Verify API_ACCESS_KEY is set in .env
grep API_ACCESS_KEY backend/.env

401 Unauthorized¶

Symptoms:

{
  "detail": "Invalid API key"
}

Cause: API key doesn't match server configuration

Solution: 1. Check API_ACCESS_KEY in backend/.env 2. Regenerate key if compromised:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Database Issues¶

Connection Refused¶

Symptoms:

psycopg2.OperationalError: could not connect to server

Cause: PostgreSQL not running or incorrect connection string

Solution:

# Check PostgreSQL is running
docker-compose ps postgres

# Verify DATABASE_URL in .env
grep DATABASE_URL backend/.env

# Restart PostgreSQL
docker-compose restart postgres

pgvector Extension Not Found¶

Symptoms:

ERROR: extension "vector" does not exist

Cause: pgvector extension not installed

Solution:

# For Docker Compose
docker-compose down -v
docker-compose up  # Will run init-pgvector.sql

# For local PostgreSQL
psql -d greengovrag -c "CREATE EXTENSION vector;"

Migration Errors¶

Symptoms:

alembic.util.exc.CommandError: Can't locate revision identified by 'abc123'

Cause: Database schema out of sync

Solution:

cd backend

# Check current revision
alembic current

# Upgrade to latest
alembic upgrade head

# If still failing, reset database (WARNING: data loss)
alembic downgrade base
alembic upgrade head

Vector Store Issues¶

Qdrant Connection Timeout¶

Symptoms:

httpx.ConnectTimeout: timed out

Cause: Qdrant not running or wrong URL

Solution:

# Check Qdrant is running
curl http://localhost:6333/health

# Verify QDRANT_URL in .env
grep QDRANT_URL backend/.env

# Restart Qdrant
docker-compose restart qdrant

Collection Not Found¶

Symptoms:

qdrant_client.exceptions.UnexpectedResponse: Collection 'greengovrag' not found

Cause: Collection hasn't been created

Solution:

# Run ETL pipeline to create collection
docker-compose up etl

# Or manually create via API
curl -X PUT http://localhost:6333/collections/greengovrag \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": {
      "size": 384,
      "distance": "Cosine"
    }
  }'

FAISS Index Missing¶

Symptoms:

FileNotFoundError: [Errno 2] No such file or directory: 'data/vectors/faiss_index'

Cause: FAISS index not yet created

Solution:

# Create data directory
mkdir -p data/vectors

# Run ETL to build index
greengovrag-cli etl run-pipeline --config configs/documents_config.yml

LLM Provider Issues¶

OpenAI Rate Limit¶

Symptoms:

openai.error.RateLimitError: Rate limit reached

Cause: Exceeded OpenAI rate limits

Solution:

Wait and retry with exponential backoff
Upgrade OpenAI plan for higher limits
Switch to Azure OpenAI (higher limits):
```
LLM_PROVIDER=azure
```

Invalid API Key¶

Symptoms:

openai.error.AuthenticationError: Incorrect API key provided

Cause: Invalid or expired LLM API key

Solution:

# Verify key is set
grep OPENAI_API_KEY backend/.env

# Test key directly
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# For Azure, check endpoint and key
grep AZURE_OPENAI backend/.env

Model Not Found¶

Symptoms:

openai.error.InvalidRequestError: The model 'gpt-5' does not exist

Cause: Model name doesn't exist or isn't available

Solution:

# For Azure, use deployment name (not model name)
LLM_MODEL=your-deployment-name  # e.g., "gpt-4o"

# For OpenAI, use valid model name
LLM_MODEL=gpt-4o  # or gpt-4o-mini

ETL Issues¶

Document Download Failed¶

Symptoms:

requests.exceptions.HTTPError: 404 Client Error

Cause: Source URL is broken or moved

Solution:

Check document source URL in configs/documents_config.yml
Manually verify URL in browser
Update config with new URL

Disable source if permanently unavailable:

- type: federal_epbc
  enabled: false  # Temporarily disable

PDF Parsing Errors¶

Symptoms:

unstructured.errors.PartitionError: Failed to parse PDF

Cause: Corrupted PDF or unsupported format

Solution:

# Check PDF is valid
file document.pdf

# Try different parser strategy
UNSTRUCTURED_STRATEGY=fast  # Options: hi_res, fast, auto

# Skip problematic document
# Edit configs/documents_config.yml to exclude

Out of Memory During Indexing¶

Symptoms:

MemoryError: Unable to allocate array

Cause: Too many chunks being processed at once

Solution:

# Reduce batch size in .env
CHUNK_BATCH_SIZE=50  # Down from 100

# Increase Docker memory limit
# docker-compose.yml: mem_limit: 4g

Performance Issues¶

Slow Query Response¶

Symptoms: Queries taking >5 seconds

Possible causes and solutions:

Cache disabled:
```
ENABLE_CACHE=true
CACHE_TTL=3600
```
Too many sources requested:
```
{"max_sources": 3}  // Instead of 10
```
Vector store not optimized:
Switch from FAISS to Qdrant for production
Enable HNSW index in Qdrant
LLM response slow:
Use faster model: gpt-4o-mini instead of gpt-4o
Reduce max_tokens in query

High Memory Usage¶

Symptoms: Container OOM killed

Solution:

# Increase Docker memory
docker-compose.yml:
  services:
    backend:
      mem_limit: 4g  # Up from 2g

# Reduce vector store memory usage
VECTOR_STORE_TYPE=qdrant  # Qdrant uses less memory than FAISS

Docker Issues¶

Port Already in Use¶

Symptoms:

Error starting userland proxy: listen tcp 0.0.0.0:8000: bind: address already in use

Solution:

# Find process using port
lsof -i :8000

# Kill process
kill -9 <PID>

# Or change port in docker-compose.yml
ports:
  - "8001:8000"  # Use port 8001 instead

Container Won't Start¶

Symptoms: Container exits immediately after starting

Solution:

# Check logs
docker-compose logs backend

# Common causes:
# 1. Missing environment variables
#    Solution: Verify .env file exists and is complete

# 2. Database migration needed
#    Solution: Run migrations manually
docker-compose exec backend alembic upgrade head

# 3. Dependency conflict
#    Solution: Rebuild images
docker-compose build --no-cache

Network Issues¶

Cannot Reach API from Host¶

Symptoms: Connection refused when calling API

Solution:

# Check API is running
docker-compose ps

# Check API is listening
docker-compose exec backend netstat -tlnp | grep 8000

# Test from inside container
docker-compose exec backend curl http://localhost:8000/api/health

# If working inside, check port mapping
docker-compose ps  # Should show 0.0.0.0:8000->8000/tcp

Getting Help¶

If you're still stuck:

Check logs: docker-compose logs -f backend
Enable debug logging: LOG_LEVEL=DEBUG in .env
Search issues: GitHub Issues
Create issue: Include logs, .env (redacted), and error messages

Troubleshooting¶

Authentication Issues¶

403 Forbidden - Missing API Key¶

401 Unauthorized¶

Database Issues¶

Connection Refused¶

pgvector Extension Not Found¶

Migration Errors¶

Vector Store Issues¶

Qdrant Connection Timeout¶

Collection Not Found¶

FAISS Index Missing¶

LLM Provider Issues¶

OpenAI Rate Limit¶

Invalid API Key¶

Model Not Found¶

ETL Issues¶

Document Download Failed¶

PDF Parsing Errors¶

Out of Memory During Indexing¶

Performance Issues¶

Slow Query Response¶

High Memory Usage¶

Docker Issues¶

Port Already in Use¶

Container Won't Start¶

Network Issues¶

Cannot Reach API from Host¶

Getting Help¶

See Also¶