# How to Troubleshoot Configuration Issues in Code‑Graph‑RAG

> Troubleshoot Code-Graph-RAG configuration issues. Learn how to fix common problems with AppConfig, environment variables, and API keys for seamless operation. Get your setup right today.

- Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag)
- Tags: how-to-guide
- Published: 2026-08-18

---

**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`](https://github.com/vitali87/code-graph-rag/blob/main/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.

```python
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:

```python
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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py)) that checks for missing credentials and raises descriptive exceptions.

```python

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

```bash
export OPENAI_API_KEY="sk-..."

```

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

```bash
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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/vector_store.py) (lines 120-130), where the backend string is normalized and validated.

```python

# 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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py), it defaults to `~/.cgr`:

```python

# 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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/config.py)). Supplying a non-integer or negative value raises validation errors during runtime.

```python

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

```python
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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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.