How to Troubleshoot Configuration Issues in Code‑Graph‑RAG

Most configuration errors in Code‑Graph‑RAG stem from the central AppConfig class failing to resolve environment variables, API keys, or backend settings correctly.

Code‑Graph‑RAG consolidates all runtime parameters into a single Pydantic BaseSettings implementation located in codebase_rag/config.py. When the application initializes, it instantiates a global settings object that pulls values from environment variables, a local .env file, or hard‑coded defaults. Misalignment in any of these layers typically surfaces as connection failures, validation errors, or silent misconfigurations.

Verify the Loaded Configuration

Before debugging specific components, confirm that the settings object contains the values you expect. The AppConfig class exposes a dict() method that dumps all resolved fields.

from codebase_rag.config import settings

def dump_settings():
    """Print all resolved configuration values."""
    for name, value in settings.dict().items():
        print(f"{name}: {value!r}")

dump_settings()

Alternatively, output the entire configuration as formatted JSON to inspect nested structures:

from codebase_rag.config import settings
print(settings.json(indent=2))

If a field returns None or an unexpected default, the environment variable name likely contains a typo or the .env file is not being read.

Resolve Missing API Keys and Credentials

External service integrations (OpenAI, Ollama, Qdrant, Milvus) require valid API keys. The AppConfig class provides a validate_api_key() method (defined around line 125 in codebase_rag/config.py) that checks for missing credentials and raises descriptive exceptions.

# Example validation pattern from config.py (line 125-130)

def validate_api_key(self, role: str = cs.DEFAULT_MODEL_ROLE) -> None:
    # Checks for missing keys and raises a helpful exception

    ...

If you encounter errors like "OpenAI API key not set", export the variable before launching the application:

export OPENAI_API_KEY="sk-..."

Or add it to a .env file in the project root:

OPENAI_API_KEY=sk-...

Fix Vector-Store Backend Errors

The vector-store backend is selected via settings.VECTOR_STORE_BACKEND. Invalid values trigger import-time failures in codebase_rag/vector_store.py (lines 120-130), where the backend string is normalized and validated.

# vector_store.py – backend selection (line 120-124)

return VectorStoreBackend(str(settings.VECTOR_STORE_BACKEND).lower())

Common misconfigurations include:

• ValueError: unknown vector store backend — Set VECTOR_STORE_BACKEND to QDRANT or MILVUS exactly.
• Connection timeouts to Qdrant — Verify that QDRANT_URL is defined for server mode or QDRANT_DB_PATH for file-based storage.
• Milvus collection errors — Ensure MILVUS_COLLECTION_NAME and MILVUS_VECTOR_DIM match the existing collection schema.

Check File-System Path Permissions

The CGR_HOME variable determines where workspaces persist on disk. Defined at line 218 in codebase_rag/config.py, it defaults to ~/.cgr:

# config.py – CGR_HOME default (line 218)

CGR_HOME: Path = Field(default_factory=lambda: Path.home() / ".cgr")

If you override this path, ensure the directory exists and the process has write permissions. Permission failures typically surface in codebase_rag/workspaces/storage.py (lines 20-30) when attempting to save or load workspace states.

Validate Batch Size and Numeric Settings

Components that process data in chunks rely on settings.resolve_batch_size() (lines 394-398 in config.py). Supplying a non-integer or negative value raises validation errors during runtime.

# config.py – batch-size resolver (line 394-398)

def resolve_batch_size(self, batch_size: int | None) -> int:
    # Validates and returns effective batch size

    ...

Always verify that BATCH_SIZE environment variables contain positive integers.

Apply Runtime Configuration Changes

Because settings is instantiated at import time, changes to environment variables after the first import are ignored. To force a reload without restarting the interpreter:

import os
from importlib import reload

# Update the environment

os.environ["VECTOR_STORE_BACKEND"] = "MILVUS"

# Reload the configuration module

import codebase_rag.config as cfg
reload(cfg)

print(cfg.settings.VECTOR_STORE_BACKEND)  # → MILVUS

Common Pitfalls and Quick Fixes

Symptom	Root Cause	Resolution
Stale configuration values	settings imported before env vars were set	Set variables before import, or use importlib.reload
Case-sensitive mismatch	Environment variables use exact field names from AppConfig	Verify spelling matches MEMGRAPH_HOST, not memgraph_host
Ignored .env file	File read only once at startup	Restart the application after editing .env
Conflicting Qdrant modes	Both QDRANT_URL and QDRANT_DB_PATH defined	Clear the unused variable; URL takes precedence

Debugging Checklist

• Print specific fields: Run print(settings.MEMGRAPH_HOST) to verify individual values.
• Check raw environment: Use print(os.getenv("MEMGRAPH_HOST")) to confirm the OS layer.
• Clear cache: Delete any generated .cgr configuration caches and restart.
• Unit-test isolation: Examine codebase_rag/tests/test_vector_store_isolation.py for examples of monkey-patching settings in test environments.

Summary

Troubleshooting Code‑Graph‑RAG configuration issues requires systematic verification of the centralized AppConfig settings:

• Dump the settings object to confirm effective values loaded from environment variables or .env files.
• Use validate_api_key() to catch missing credentials early.
• Ensure VECTOR_STORE_BACKEND matches supported enums and corresponding connection URLs are reachable.
• Verify that CGR_HOME directories exist with correct permissions.
• Reload the configuration module via importlib.reload when testing changes without a full restart.

Frequently Asked Questions

How do I reload configuration without restarting the application?

Python caches the settings instance at import time. To apply new environment variables in a running script or notebook, update os.environ then use importlib.reload on the codebase_rag.config module. This recreates the AppConfig instance with fresh values.

Why is my .env file being ignored?

The .env file is read once when the AppConfig class first instantiates. If you edit the file while the application is running, those changes remain invisible until you restart the process. Additionally, ensure the file is located in the current working directory where the application launches.

What causes "unknown vector store backend" errors?

This error originates in codebase_rag/vector_store.py when settings.VECTOR_STORE_BACKEND contains a value not present in the VectorStoreBackend enum. Acceptable values are typically QDRANT or MILVUS. Check for typos and ensure the value is uppercase if required by your version.

How do I validate that all required API keys are set?

Call settings.validate_api_key() after importing the settings object. This method checks for the presence of keys required by the configured model provider (OpenAI, Ollama, etc.) and raises a clear exception identifying which variable is missing, allowing you to fix the configuration before runtime operations begin.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}