Skip to main content

Common Errors

This guide covers frequently encountered errors and their solutions.

Database Errors​

Connection Refused​

Error: connection refused to localhost:5432

Cause: PostgreSQL is not running.

Solution:

docker compose up -d

pgvector Extension Missing​

Error: extension "vector" is not available

Cause: pgvector extension not installed.

Solution: Ensure you're using the pgvector Docker image:

# docker-compose.yml
image: pgvector/pgvector:pg16

Embedding Errors​

Dimension Mismatch​

Error: expected 1536 dimensions, got 3072

Cause: Embedding model mismatch between stored vectors and query.

Solution: Ensure AZURE_EMBEDDING_DEPLOYMENT matches the model used during ingestion. If you change models, you'll need to re-embed all documents.

Rate Limit Exceeded​

Error: Rate limit exceeded. Retry after 60 seconds.

Cause: Too many API requests.

Solution:

  1. Use batch enrichment for large operations
  2. Add delays between requests
  3. Check your API quota

Ingestion Errors​

Invalid JSON Format​

Error: Failed to parse conversations.json

Cause: Export file is corrupted or in wrong format.

Solution:

  1. Verify the export is from the correct source
  2. Check file encoding (should be UTF-8)
  3. Validate JSON syntax

Duplicate Document​

Warning: Document already exists, skipping

Cause: Document with same hash already ingested.

Solution: This is expected behavior. Use --force to re-ingest if needed.

Search Errors​

No Results Found​

No results found for query: "my search"

Possible causes:

  1. No matching content in knowledge base
  2. Query too specific

Solutions:

  1. Check engram stats to verify documents exist
  2. Try broader search terms
  3. Use --hybrid for combined semantic + keyword search

Configuration Errors​

Missing Environment Variable​

Error: AZURE_OPENAI_ENDPOINT not set

Solution: Set required environment variables in .env:

AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_API_KEY=your_key

Invalid API Key​

Error: 401 Unauthorized

Solution: Verify your API key is correct and has appropriate permissions.

Getting Help​

If you encounter an error not listed here:

  1. Check the FAQ
  2. Search existing GitHub Issues
  3. Open a new issue with:
    • Error message
    • Steps to reproduce
    • Engram version (engram --version)
    • Environment details