Troubleshooting Guide

Common issues and solutions for CodeGraph.

Table of Contents

Installation Issues

DuckDB Version Mismatch

Symptom:

duckdb.InvalidInputException: Catalog Error: ...DuckPGQ...

Solution:

CodeGraph requires duckdb>=1.4.4 for the DuckPGQ extension. Check your version:

python -c "import duckdb; print(duckdb.__version__)"

# Upgrade if below 1.4.4
pip install "duckdb>=1.4.4"

CUDA Not Found

Symptom:

RuntimeError: CUDA not available

Solution:

# Check CUDA installation
nvidia-smi
nvcc --version

# Reinstall PyTorch with CUDA
pip uninstall torch
pip install torch --index-url https://download.pytorch.org/whl/cu118

DuckDB Connection Failed

Symptom:

duckdb.IOException: Could not open file 'data/projects/postgres.duckdb'

Solution:

# Check file exists
ls -la data/projects/postgres.duckdb

# Check permissions
chmod 644 data/projects/postgres.duckdb

# Check not locked by another process
lsof data/projects/postgres.duckdb  # Linux/Mac

ChromaDB Initialization Failed

Symptom:

chromadb.errors.ChromaDBError: Collection not found

Solution:

# Verify chroma_db/ directory exists (NOT chromadb_storage/)
ls -la chroma_db/

# Reinitialize if needed
python scripts/init_vector_store.py

Warning: Never delete the chroma_db/ directory. It contains 250K+ indexed documents and reimporting takes significant time.

Import Errors

Symptom:

ModuleNotFoundError: No module named 'src'

Solution:

# Ensure you're in the project root
cd /path/to/codegraph

# Add to PYTHONPATH
export PYTHONPATH="${PYTHONPATH}:$(pwd)"

# Or use pip install in development mode
pip install -e .

Test Issues

DuckDB Import Bug with pytest

Symptom:

ImportError: DuckDB extension error when running pytest

Solution:

Always run tests from the tests/ directory, never from the project root:

# CORRECT
pytest tests/ -v

# WRONG — causes DuckDB import bug
pytest .

Pytest Capture Error on Windows

Symptom (Python 3.13 on Windows):

ValueError: I/O operation on closed file

Full test suite crashes with pytest 9.0.2 + Python 3.13 on Windows.

Solution:

# Use -s flag to disable output capture
pytest tests/ -v -s

Individual test block runs are unaffected; the issue only manifests in full-suite runs.

LLM Provider Issues

GigaChat Authentication Failed

Symptom:

401 Unauthorized: Invalid credentials

Solution:

# Check environment variable
echo $GIGACHAT_AUTH_KEY

# Set if missing
export GIGACHAT_AUTH_KEY="your_key"

# Verify in Python
python -c "import os; print(os.environ.get('GIGACHAT_AUTH_KEY', 'NOT SET'))"

Local LLM Out of Memory

Symptom:

CUDA out of memory

Solution:

# Reduce model layers in config.yaml → llm.local
llm:
  local:
    n_gpu_layers: 20  # Reduce from -1
    n_ctx: 4096       # Reduce context window

Or use a smaller quantization:

# Use Q4_K_M instead of Q5_K_M

LLM Response Timeout

Symptom:

TimeoutError: LLM did not respond within timeout

Solution:

Timeout is configured per LLM provider in config.yaml:

# Increase timeout for specific provider
llm:
  gigachat:
    timeout: 120  # seconds (default: 60)
  yandex:
    timeout: 300  # seconds (default: 180)

Query Issues

No Results Found

Symptom:

No methods found matching query

Solutions: 1. Check spelling - Method names are case-sensitive 2. Use partial match - Try *Transaction* instead of CommitTransaction 3. Check database - Verify data exists: sql SELECT COUNT(*) FROM nodes_method WHERE full_name LIKE '%Transaction%';

Slow Query Performance

Symptom: Query takes more than 10 seconds

Solutions:

# Reduce search scope in config.yaml
retrieval:
  top_k_qa: 3      # Reduce from default

# Switch to vector-only mode (faster than hybrid)
workflows:
  handlers:
    retrieval_weights:
      mode: vector_only   # Instead of "hybrid"

Incorrect Results

Symptom: Answers don’t match expected results

Solutions: 1. Refine question - Be more specific 2. Check domain - Ensure correct domain is set 3. Verify embeddings - Re-generate if corrupted: bash python -m src.cli.import_commands full --path ./source --language c

GoCPG Issues

GoCPG Parse Fails

Symptom:

Error: failed to parse source files

Solution:

# Verify GoCPG binary is built with CGO
CGO_ENABLED=1 go build -o gocpg ./cmd/gocpg

# Check supported frontends
./gocpg frontends

# Re-parse with verbose logging
./gocpg parse --input=/path/to/source --output=data/projects/postgres.duckdb --lang=c --verbose

Memory Issues

Out of Memory During Processing

Symptom:

MemoryError: Unable to allocate

Solutions:

# Reduce batch sizes in config.yaml
batch_processing:
  extraction_default_limit: 500   # Reduce from default
  chromadb_batch: 100             # Reduce ChromaDB batch size

Benchmarks Out of Memory

Symptom: Hypothesis or benchmark runs consume all memory

Solution:

# Run benchmarks in batches
python -m src.cli hypothesis run --max-questions 3 --offset 0
python -m src.cli hypothesis run --max-questions 3 --offset 3

High Memory Usage

Symptom: System becomes unresponsive

Solutions:

# Monitor memory usage
watch -n 1 'free -h'

# Clear query caches
python -c "from src.optimization.query_cache import QueryCache; QueryCache().clear()"

# ChromaDB is disk-backed by default (chroma_db/ directory)
# Check its size: du -sh chroma_db/

API and MCP Issues

Port Already in Use

Symptom:

OSError: [Errno 98] Address already in use

Solution:

# Check what's using the port
lsof -i :8000  # API default port
lsof -i :27495 # MCP default port

# Kill the process or use a different port
uvicorn src.api.main:app --port 8001
python -m src.mcp --port 27496

JWT Secret Not Configured

Symptom:

ValueError: API_JWT_SECRET must be at least 64 characters

Solution:

# Generate and set a JWT secret (64+ characters)
export API_JWT_SECRET=$(python -c "import secrets; print(secrets.token_hex(64))")

Debugging

Enable Debug Logging

Set debug level in your script:

import logging
logging.basicConfig(level=logging.DEBUG)

Or configure in config.yaml under the security logging section:

security:
  logging:
    request_logging: true
    audit_logging: true
    log_request_body: true

Check Component Status

# Diagnostic script
import duckdb
from src.services.cpg import CPGQueryService
from src.retrieval.vector_store_real import VectorStoreReal

# Check DuckDB
cpg = CPGQueryService()
conn = cpg._get_connection()
result = conn.execute("SELECT COUNT(*) FROM nodes_method").fetchone()
print(f"Methods in DB: {result[0]}")

# Check Vector Store
vs = VectorStoreReal()
vs.initialize_collections()  # Required before accessing collections
print(f"QA docs: {vs.qa_collection.count()}")

# Check LLM
from src.llm.llm_interface_compat import get_llm
llm = get_llm()
print(f"LLM: {type(llm).__name__}")

Generate Debug Report

python -c "
import sys
import platform

print('=== System Info ===')
print(f'Python: {sys.version}')
print(f'Platform: {platform.platform()}')

print('\n=== CUDA ===')
try:
    import torch
    print(f'PyTorch: {torch.__version__}')
    print(f'CUDA available: {torch.cuda.is_available()}')
    if torch.cuda.is_available():
        print(f'CUDA version: {torch.version.cuda}')
        print(f'GPU: {torch.cuda.get_device_name(0)}')
except ImportError:
    print('PyTorch not installed')

print('\n=== Dependencies ===')
import duckdb
print(f'DuckDB: {duckdb.__version__}')

import chromadb
print(f'ChromaDB: {chromadb.__version__}')
"

Getting Help

If issues persist:

  1. Check stderr - Logging output goes to stderr by default (no log file)
  2. Search existing issues in the repository
  3. Create a new issue with: - Error message - Steps to reproduce - Debug report output - config.yaml (sensitive values removed)

Next Steps