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

OpenViking Initialization Failed

Symptom:

openviking.errors.OpenVikingError: Collection not found

Solution:

# Verify openviking_data/ directory exists (NOT openviking_storage/)
ls -la openviking_data/

# Reinitialize if needed
python -m src.cli reindex --replace

Warning: Never delete the openviking_data/ 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
  openviking_batch: 100             # Reduce OpenViking 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()"

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

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 argparse

from src.config import get_unified_config
from src.context.contracts.contracts import ProjectScope
from src.context.openviking.openviking_retrieval_adapter import OpenVikingRetrievalAdapter
from src.services.cpg import CPGQueryService

parser = argparse.ArgumentParser()
parser.add_argument("--db", required=True, help="Resolved project CPG DuckDB path")
parser.add_argument("--project", default="codegraph")
parser.add_argument("--namespace", default="projects/local/codegraph")
args = parser.parse_args()

# Check CPG reads through GoCPG gRPC. Runtime diagnostics must not open DuckDB locally.
with CPGQueryService(db_path=args.db, grpc_only=True) as cpg:
    rows = cpg.execute_query("SELECT COUNT(*) AS methods FROM nodes_method")
    print(f"Methods in CPG: {rows[0].get('methods', 0) if rows else 0}")

# Check OpenViking project memory. There is no local vector-store compatibility layer.
scope = ProjectScope(
    tenant_id="local",
    group_id="local",
    project_id=args.project,
    tenant_key="local",
    group_key="local",
    project_key=args.project,
    user_key="diagnostics",
    agent_key="codegraph",
    project_name=args.project,
    db_path=args.db,
    collection_prefix=f"local_{args.project}",
    namespace=args.namespace,
    agent_namespace=f"{args.namespace}/agents/codegraph",
    user_namespace=f"{args.namespace}/users/diagnostics",
)
adapter = OpenVikingRetrievalAdapter(scope, get_unified_config().openviking)
stats = adapter.get_stats()
print(f"OpenViking provider: {stats['provider']} ({stats['read_mode']})")
print(f"Documentation hits: {len(adapter.retrieve_documentation('troubleshooting', top_k=1))}")

# 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 openviking
print(f'OpenViking: {openviking.__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