Skip to content

troubleshooting.md

Latest commit

 

History

History
1999 lines (1551 loc) · 44.6 KB

troubleshooting.md

File metadata and controls

1999 lines (1551 loc) · 44.6 KB
Raw

CIE Troubleshooting Guide

A comprehensive guide for diagnosing and resolving common CIE issues.

Quick Links:

Quick Diagnostics

Run these commands first to gather system information:

# System information
cie --version          # Shows version, Go version, build info

# Configuration health
cie config show        # Display effective configuration
cie status             # Verify connection to server and index status

# Check local data exists
ls ~/.cie/data/

# Quick embedding test (if using Ollama)
curl http://localhost:11434/api/tags

What to look for:

  • cie --version should show version without library errors
  • go version should be 1.24 or newer
  • cie config show should display valid YAML without errors
  • cie status should show function count > 0 if indexed
  • ~/.cie/data/<project_id>/ directory should exist with files if project is indexed
  • Ollama curl should return JSON list of models (if using Ollama for embeddings)

Installation Issues

Issue: CozoDB Library Not Found (macOS/Linux)

Symptoms:

  • error while loading shared libraries: libcozo_c.so
  • Library not loaded: /.../libcozo_c.dylib
  • fatal error: semawakeup on Darwin signal stack (macOS specific)

Cause: CIE uses CozoDB as its graph engine, which requires a C library. If the binary was not compiled with static linking or the dynamic library is missing from the search path, it will fail to start.

Solution:

  1. Install via Homebrew (Recommended): The easiest solution is to install the pre-built binary via Homebrew:

    brew tap kraklabs/cie && brew install cie

  2. Rebuild with Static Linking: If you must build the CLI locally, use the provided Makefile which handles library downloading and static linking automatically:

    make build

  3. macOS "semawakeup" fix: If you encounter a crash with semawakeup on Darwin signal stack, it's usually due to a conflict between Go's signal handling and the CozoDB library on macOS. We've mitigated this in the latest version by using static linking. Use Homebrew or the install script for pre-built binaries.

Issue: Go Version Too Old

Symptoms:

  • go: module requires Go 1.24 or later
  • Build errors mentioning language features not available
  • Installation fails during go install

Cause: CIE requires Go 1.24 or newer for language features and standard library APIs. Older Go versions lack required functionality.

Solution:

Check current version:

go version
# If < 1.24, upgrade:

macOS:

brew upgrade go
# or download from: https://go.dev/dl/

Linux:

# Remove old version
sudo rm -rf /usr/local/go

# Download latest
wget https://go.dev/dl/go1.24.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.24.0.linux-amd64.tar.gz

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH=$PATH:/usr/local/go/bin

Verify:

go version
# Should show: go version go1.24.X ...

Related:

Issue: CGO_ENABLED Not Set

Symptoms:

  • undefined reference to 'cozo_open' and other cozo_* functions
  • Build succeeds but binary crashes with library errors
  • Linking errors during go build

Cause: CIE uses CozoDB's C bindings (CGO). CGO must be enabled during build. If CGO_ENABLED=0, Go will not link against C libraries.

Solution:

Use pre-built binary (Recommended):

# Homebrew (no CGO issues)
brew tap kraklabs/cie && brew install cie

Or build with CGO enabled:

# Set for current session
export CGO_ENABLED=1

# Build from source (after cloning the repo)
CGO_ENABLED=1 go build -o cie ./cmd/cie

Make permanent (add to ~/.bashrc or ~/.zshrc):

echo 'export CGO_ENABLED=1' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc

Verify:

go env CGO_ENABLED
# Should output: 1

cie --version
# Should work without errors

Related:

Issue: Library Path Not Set on Linux

Symptoms:

  • error while loading shared libraries: libcozo_c.so: cannot open shared object file
  • Library exists at /usr/local/lib/libcozo_c.so but not found
  • cie --version works as root but not as regular user

Cause: Linux requires libraries to be in the dynamic linker's search path. Even if the library is installed, the system may not know where to find it at runtime.

Solution:

Option 1: Update LD_LIBRARY_PATH (temporary):

export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
cie --version

Option 2: Update ldconfig (permanent, recommended):

# Create config file
echo "/usr/local/lib" | sudo tee /etc/ld.so.conf.d/local.conf

# Refresh cache
sudo ldconfig

# Verify library is found
ldconfig -p | grep cozo
# Should show: libcozo_c.so (libc6,x86-64) => /usr/local/lib/libcozo_c.so

Option 3: Install to standard location:

# Move library to system library path
sudo mv /usr/local/lib/libcozo_c.so /usr/lib/libcozo_c.so
# or
sudo mv /usr/local/lib/libcozo_c.so /usr/lib64/libcozo_c.so  # RHEL/Fedora

Verify:

cie --version
# Should work without LD_LIBRARY_PATH

Related:

Indexing Problems

Issue: No Functions Found

Symptoms:

  • Functions indexed: 0 after running cie index
  • cie status shows 0 functions
  • Search returns no results even though code files exist

Cause: This typically happens when:

  1. No supported files exist in the project (only supports .go, .py, .js, .ts, .tsx)
  2. Exclusion patterns are too broad and exclude all code files
  3. Tree-sitter parsers fail to extract functions from files
  4. Files are outside the indexed directory path

Solution:

  1. Check supported file extensions:

    # Count supported files
find . -type f \( -name "*.go" -o -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.tsx" \) | wc -l

    If count is 0, your project uses unsupported languages.

  2. Check exclusion patterns:

    cie config show | grep exclude

    Common overly broad patterns:

    • **/* (excludes everything!)
    • * (excludes all files in root)

    Fix: Edit .cie/project.yaml, set sensible exclusions:

    exclude:
  - "node_modules/**"
  - "vendor/**"
  - "*.test.go"
  - "**/*_test.go"

  3. Check indexing logs:

    cie index --debug
# Look for parse errors or excluded file messages

  4. Verify index path:

    cie status
# Check "Project Path" matches your code directory

    If wrong, reinitialize:

    cd /path/to/your/code
cie init
cie index

Verify:

cie status
# Should show: Functions indexed: > 0

Related:

Issue: Tree-sitter Parse Errors

Symptoms:

  • [ERROR] Failed to parse file: syntax error at line X
  • Some files indexed but others skipped
  • Function count lower than expected

Cause: Tree-sitter parsers encounter invalid syntax in source files. This can happen with:

  • Syntax errors in the code
  • Experimental language features not supported by tree-sitter
  • Macro-heavy code (C preprocessor, Rust macros)
  • Files with incorrect extensions (.js file containing TypeScript)

Solution:

  1. Review parse errors:

    cie index --debug 2>&1 | grep "Failed to parse"
# Note which files fail

  2. Check syntax of failing files:

    # For Go
go build ./path/to/failing/file.go

# For TypeScript
tsc --noEmit path/to/failing/file.ts

# For Python
python -m py_compile path/to/failing/file.py

  3. Exclude problematic files if unfixable:

    # .cie/project.yaml
exclude:
  - "generated/**"         # Generated code often has parse issues
  - "**/*.generated.go"
  - "path/to/macro-heavy/file.c"

  4. Check tree-sitter grammar version:

    cie --version
# Shows tree-sitter grammar versions

    If outdated, update CIE to latest version:

    brew upgrade cie
# Or: curl -sSL https://raw.githubusercontent.com/kraklabs/cie/main/install.sh | sh

Note: CIE gracefully skips unparseable files and continues indexing. Parse errors reduce index completeness but don't block indexing.

Verify:

cie index --debug 2>&1 | grep -c "Failed to parse"
# Should decrease after fixes

Related:

Issue: Embedding Timeout (Ollama Connection Failed)

Symptoms:

  • failed to connect to Ollama at http://localhost:11434
  • context deadline exceeded during indexing
  • Indexing hangs at embedding generation stage

Cause: CIE cannot reach the Ollama embedding provider. Common causes:

  • Ollama is not running
  • Ollama is running on a different port
  • Firewall blocking connection
  • Ollama crashed or out of memory

Solution:

  1. Check if Ollama is running:

    curl http://localhost:11434/api/tags

    If connection refused:

    # Start Ollama
ollama serve

# Or on macOS with Homebrew service:
brew services start ollama

  2. Verify Ollama model is available:

    ollama list
# Should show nomic-embed-text or configured model

    If model missing:

    ollama pull nomic-embed-text

  3. Check Ollama port in config:

    cie config show | grep ollama
# Verify URL matches where Ollama is running

    Fix if wrong:

    # .cie/project.yaml
embedding:
  provider: ollama
  ollama:
    url: "http://localhost:11434"  # Match your Ollama port
    model: "nomic-embed-text"

  4. Check firewall rules:

    # macOS
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getblockall

# Linux
sudo iptables -L -n | grep 11434

Verify:

curl http://localhost:11434/api/tags
# Should return JSON: {"models":[...]}

cie index
# Should proceed without timeout

Related:

Issue: Indexing Without Ollama

Symptoms:

  • Warning messages about embedding failures during cie index
  • Semantic search returns no results after indexing
  • cie_index_status shows functions but no embeddings

Cause: Ollama is not running or the embedding model is not pulled. This is not an error -- CIE is designed to work without embeddings.

What works without embeddings: All 20+ tools except cie_semantic_search and cie_find_similar_functions:

  • cie_grep, cie_find_function, cie_find_callers, cie_find_callees
  • cie_trace_path, cie_get_call_graph, cie_list_endpoints
  • cie_get_function_code, cie_directory_summary, and more

To enable semantic search:

brew install ollama
ollama pull nomic-embed-text
ollama serve
cie index --full  # Re-index to generate embeddings

Issue: Out of Memory During Indexing

Symptoms:

  • cie index killed with Killed message
  • System becomes unresponsive during indexing
  • dmesg shows OOM killer messages: Out of memory: Kill process

Cause: Indexing large projects generates many embeddings simultaneously, consuming significant RAM. Default concurrency may be too high for available memory.

Solution:

  1. Reduce embedding worker concurrency:

    # .cie/project.yaml
indexing:
  embed_workers: 1        # Reduce from default 4
  batch_size: 50          # Reduce from default 100

  2. Increase system swap (Linux):

    # Check current swap
swapon --show

# Add 4GB swap file
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Make permanent (add to /etc/fstab)
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

  3. Index in stages for large projects:

    # Index subdirectories separately
cd backend/
cie init
cie index

cd ../frontend/
cie init
cie index

  4. Use lighter embedding model:

    # .cie/project.yaml - Use smaller model
embedding:
  provider: ollama
  ollama:
    model: "mxbai-embed-large"  # Smaller than nomic-embed-text

  5. Monitor memory during indexing:

    # Watch memory usage
watch -n 1 free -h

# Or with htop
htop

Verify:

cie index
# Should complete without being killed

Related:

Issue: Mutation Batch Too Large

Symptoms:

  • mutation statement exceeds max size: X bytes (limit: Y)
  • Error shows statement preview with CozoDB mutation
  • Indexing stops partway through

Cause: CIE batches mutations (inserts) to CozoDB for performance. If a single function's AST or embedding is very large, the batch may exceed CozoDB's mutation size limit (typically 10MB).

This happens with:

  • Extremely long functions (>1000 lines)
  • Functions with huge string literals
  • Large generated code files

Solution:

  1. Reduce batch size:

    # .cie/project.yaml
indexing:
  batch_size: 50   # Reduce from default 100

  2. Exclude problematic files:

    The error message shows a statement preview. Look for the filename:

    Statement preview: {put nodes [[path/to/huge_file.go ...

    Exclude it:

    # .cie/project.yaml
exclude:
  - "path/to/huge_file.go"
  - "**/*.generated.go"  # Often has huge functions

  3. Refactor large functions (if you own the code):

    Functions >500 lines are hard to index and hard to understand. Consider breaking them up:

    // Before: 1000-line function
func ProcessEverything() { ... }

// After: Smaller functions
func ProcessStep1() { ... }
func ProcessStep2() { ... }
func ProcessEverything() {
    ProcessStep1()
    ProcessStep2()
}

Verify:

cie index
# Should complete without mutation size errors

Related:

Issue: Slow Indexing

Symptoms:

  • Indexing takes >5 minutes for a small project (<10k LOC)
  • Progress appears to stall at embedding generation
  • CPU usage low but indexing not progressing

Cause: Most often caused by slow embedding generation:

  • Using a remote embedding API with high latency
  • Ollama running on CPU instead of GPU
  • Network issues with API provider
  • Embedding model is very large

Solution:

  1. Check embedding provider latency:

    # Test Ollama response time
time curl -X POST http://localhost:11434/api/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model":"nomic-embed-text","prompt":"test"}'

# Should respond in <1 second for Ollama

  2. Switch to faster provider:

    Fastest (local Ollama):

    # .cie/project.yaml
embedding:
  provider: ollama
  ollama:
    url: "http://localhost:11434"
    model: "nomic-embed-text"

    Fast (OpenAI - requires API key):

    embedding:
  provider: openai
  openai:
    api_key: "${OPENAI_API_KEY}"
    model: "text-embedding-3-small"  # Smaller = faster

  3. Increase embedding workers (if provider is fast):

    # .cie/project.yaml
indexing:
  embed_workers: 4  # Increase from default 1

    Note: Only increase if embeddings are fast (<100ms each). Otherwise you'll just queue up slow requests.

  4. Use indexing debug mode to identify bottleneck:

    cie index --debug
# Look for which stage is slow:
# - "Parsing..." stage (parser issue)
# - "Generating embeddings..." stage (embedding provider issue)
# - "Writing to database..." stage (disk I/O issue)

  5. Check disk I/O (less common):

    # Monitor disk usage during indexing
iostat -x 1

# If disk is bottleneck, move .cie/db to SSD

Verify:

time cie index
# Should complete in <2 minutes for project with <50k LOC

Related:

Issue: File Exclusion Patterns Not Working

Symptoms:

  • node_modules/ or vendor/ files still being indexed
  • Test files included despite **/*_test.go exclusion
  • Unexpected files in index

Cause: Exclusion patterns are glob patterns, not regex. Common mistakes:

  • Using regex syntax in glob patterns
  • Wrong pattern syntax for nested directories
  • Pattern doesn't match file path structure
  • Patterns case-sensitive but filenames use different case

Solution:

  1. Check current exclusion patterns:

    cie config show | grep -A 10 exclude

  2. Use correct glob syntax:

    Common patterns:

    # .cie/project.yaml
exclude:
  # Directories (note the /**)
  - "node_modules/**"       # All files under node_modules/
  - "vendor/**"
  - ".git/**"

  # File patterns
  - "**/*_test.go"          # All Go test files
  - "**/*.test.js"          # All JS test files
  - "*.md"                  # Markdown files in root only
  - "**/*.md"               # All markdown files (recursive)

  # Specific files
  - "README.md"             # Specific file in root
  - "docs/generated.md"     # Specific file with path

    Common mistakes:

    # No Wrong
exclude:
  - "node_modules"     # Only matches file named "node_modules", not directory contents
  - "*.test.*"         # Only matches root level
  - "test/.*"          # Regex syntax doesn't work

# Yes Correct
exclude:
  - "node_modules/**"  # Matches all contents
  - "**/*.test.*"      # Matches all test files recursively
  - "test/**"          # Glob syntax

  3. Test patterns before full reindex:

    # List files that will be indexed
find . -type f \( -name "*.go" -o -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.tsx" \) \
  -not -path "./node_modules/*" \
  -not -path "./vendor/*"

  4. Reindex after fixing patterns:

    # Full reindex
rm -rf .cie/db
cie index

# Or incremental (may not catch all changes)
cie index

Verify:

cie status
# Check file count matches expectations

# Check for specific excluded files
cie query "?[name, file_path] := *cie_function{name, file_path}, file_path ~ 'node_modules'"
# Should return empty if node_modules excluded correctly

Related:

Query Errors

Issue: Index Not Found

Symptoms:

  • database not initialized
  • no such table: cie_function
  • cie status shows Index: Not found

Cause: CIE hasn't indexed the project yet, or the .cie/db directory was deleted/corrupted.

Solution:

  1. Check if index exists:

    ls -la .cie/db
# Should show database files

    If directory doesn't exist:

    cie init    # Initialize project
cie index   # Create index

  2. If index exists but corrupted:

    # Backup corrupted index (optional)
mv .cie/db .cie/db.backup

# Rebuild index
cie index

  3. Check you're in correct directory:

    pwd
# Should be project root with .cie/ directory

# If wrong directory:
cd /path/to/your/project
cie status

  4. Check config file exists:

    cat .cie/project.yaml
# Should show config

    If missing:

    cie init

Verify:

cie status
# Should show:
# Index: OK (X functions, last indexed: ...)

Related:

Issue: Connection Refused to Edge Cache

Symptoms:

  • connection refused when querying
  • http://localhost:8080 connection refused
  • MCP tools timeout

Cause: This error only applies when using remote mode (with edge_cache configured in .cie/project.yaml). If you are using embedded mode (the default, with no edge_cache set), connection errors should not occur -- CIE reads directly from the local database.

Solution:

If using embedded mode (default):

Connection refused errors should not happen. If they do, verify your config does not have edge_cache set:

cie config show | grep edge_cache
# Should be empty or not present

If edge_cache is set and you don't need a remote server, remove it from .cie/project.yaml or set it to an empty string.

If using remote mode (edge_cache configured):

  1. Check if the remote server is running:

    curl http://your-server:8080/health

  2. Check config points to correct URL:

    cie config show | grep edge_cache

    Fix if wrong:

    # .cie/project.yaml
cie:
  edge_cache: "http://your-server:8080"

Note: Most users don't need a remote Edge Cache. Embedded mode (the default) is sufficient for local development. Remote mode is only required for:

  • Enterprise/distributed deployments
  • Multiple projects sharing one index
  • Network-accessible query server

Verify:

# For embedded mode:
cie status
# Should show index status without connection errors

# For remote mode:
curl http://your-server:8080/health
# Should return: {"status":"ok"}

Related:

Issue: Empty Search Results

Symptoms:

  • cie_semantic_search returns no results
  • cie_find_function finds nothing
  • cie status shows functions indexed but queries return empty

Cause: Multiple possible causes:

  1. Query doesn't match indexed content
  2. Minimum similarity threshold too high
  3. Index missing embeddings
  4. Wrong project path
  5. Query syntax error

Solution:

  1. Check index has content:

    cie status
# Should show: Functions indexed: > 0

  2. Try broader queries:

    For semantic search:

    # Too specific (may find nothing)
cie query --semantic "Redis connection pool with retry logic"

# More general (better)
cie query --semantic "database connection"

  3. Lower similarity threshold:

    # Default min_similarity is 0.7 (70%)
cie query --semantic "authentication" --min-similarity 0.5

  4. Check if embeddings were generated:

    cie index --debug 2>&1 | grep "Generating embeddings"
# Should show embedding generation completed

    If embeddings missing:

    # Reindex with embeddings
rm -rf .cie/db
cie index

  5. Use English queries (important!):

    CIE keyword boosting matches English function names:

    # No May find nothing
cie query --semantic "lógica de autenticación"

# Yes Better
cie query --semantic "authentication logic"

  6. Try different query types:

    # Semantic search
cie query --semantic "http handler"

# Text search (literal matching)
cie query --text "Handler" --mode substring

# Function name
cie query --function "HandleAuth"

# List all functions
cie query "?[name, file_path] := *cie_function{name, file_path}"

Verify:

# Should return results:
cie query --semantic "function" --min-similarity 0.3

Related:

Issue: Timeout Errors

Symptoms:

  • query timeout exceeded
  • context deadline exceeded (30s)
  • Queries hang and eventually fail

Cause: Complex queries on large indexes can exceed default 30-second timeout. Common with:

  • Semantic search across >100k functions
  • Complex Datalog queries with many joins
  • Full-text search without filters

Solution:

  1. Narrow query scope with filters:

    # Too broad (may timeout)
cie query --semantic "handler"

# Narrower (faster)
cie query --semantic "handler" --path "internal/http"

  2. Use more specific queries:

    # Broad (slow)
cie query --text "func"

# Specific (fast)
cie query --function "HandleAuth"

  3. Limit result count:

    # Returns first 10 instead of all matches
cie query --semantic "handler" --limit 10

  4. Optimize index (rebuild):

    # Compact database
rm -rf .cie/db
cie index

  5. Check index size:

    du -sh .cie/db
# If >1GB, consider excluding more files

  6. Increase timeout (if query is legitimately complex):

    # .cie/project.yaml
query:
  timeout: 60s  # Increase from default 30s

Verify:

# Should complete quickly:
time cie query --semantic "handler" --limit 10
# Should be <5 seconds

Related:

Issue: CozoDB Query Errors

Symptoms:

  • compilation error in Datalog
  • relation not found: cie_function
  • type mismatch in query
  • invalid CozoScript syntax

Cause: Raw CozoDB queries use Datalog syntax. Common errors:

  • Wrong relation name (typo in table name)
  • Missing fields in query
  • Type mismatch (e.g., comparing string to number)
  • Invalid CozoScript syntax

Solution:

  1. Use CIE query tools instead of raw CozoScript:

    Instead of:

    # No Raw CozoScript (error-prone)
cie query "?[name] := *cie_func{name}"  # Wrong table name

    Use:

    # Yes CIE query functions (validated)
cie query --function "HandleAuth"
cie query --semantic "authentication"

  2. Check relation names:

    Available relations:

    • cie_function - Function definitions
    • cie_call - Function calls (caller → callee)
    • cie_type - Type definitions
    • cie_file - File metadata
    # List all functions
cie query "?[name, file_path] := *cie_function{name, file_path}"

  3. Verify field names:

    # Show schema
cie query "?[relations] := show_relations{relations}"

# Show fields in cie_function
cie query "?[columns] := show_columns{table: 'cie_function', columns}"

  4. Check query syntax:

    Common syntax rules:

    • Variables start with lowercase or _
    • Relations use *table_name{field1, field2}
    • Patterns use :- (implies)
    • Multiple conditions use , (and) or ; (or)
    # Yes Correct syntax
cie query "?[name, file] := *cie_function{name, file_path: file}"

# No Wrong
cie query "?[name, file] := *cie_function{name file}"  # Missing :

Verify:

# Should return results without errors:
cie query "?[name] := *cie_function{name} :limit 5"

Related:

MCP Integration Issues

Issue: MCP Tools Return No Results After Indexing

Symptoms:

  • Ran cie index and data was indexed locally (to ~/.cie/data/)
  • MCP tools return no results or "database not initialized"
  • cie status shows functions indexed but MCP tools don't find them

Cause: The MCP server may not be finding the local database. In embedded mode (default), cie --mcp reads directly from ~/.cie/data/<project_id>/.

Solution:

  1. Verify the index exists:

    cie status
# Should show function count > 0
ls ~/.cie/data/
# Should show your project_id directory

  2. Ensure MCP config uses the correct working directory:

    Claude Code (~/.claude/mcp.json or project .claude/mcp.json):

    {
  "mcpServers": {
    "cie": {
      "command": "cie",
      "args": ["--mcp"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

  3. Re-index if needed:

    cie index --full

Verify:

cie status
# Should show: Functions indexed: > 0

Related:

Issue: MCP Server Won't Start

Symptoms:

  • cie --mcp hangs without output
  • cie --mcp exits immediately with error
  • MCP server starts but tools don't appear in Claude Code/Cursor

Cause: Common issues:

  • Config file not found
  • Port already in use
  • Invalid MCP config in Claude Code/Cursor
  • Project not indexed

Solution:

  1. Check project is initialized:

    ls .cie/project.yaml
# Should exist

cie status
# Should show index exists

    If not:

    cie init
cie index

  2. Test server directly:

    cie --mcp
# Should output:
# [MCP] Server started on stdio
# [MCP] Project: /path/to/project
# [MCP] Waiting for requests...

    If errors, check:

    cie config validate
# Should pass

  3. Check Claude Code/Cursor config:

    Claude Code (~/.claude/mcp.json or project .claude/mcp.json):

    {
  "mcpServers": {
    "cie": {
      "command": "cie",
      "args": ["--mcp"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

    Cursor (.cursor/mcp.json):

    {
  "mcpServers": {
    "cie": {
      "command": "cie",
      "args": ["--mcp"]
    }
  }
}

  4. Test MCP protocol manually:

    # Send test request (MCP uses JSON-RPC over stdio)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | cie --mcp
# Should return list of tools

  5. Check server logs:

    # Run with debug logging
cie --mcp --debug

Verify:

# In Claude Code/Cursor, you should see CIE tools:
# - cie_semantic_search
# - cie_find_function
# - cie_list_endpoints
# (and 20+ more tools)

Related:

Issue: Port Already in Use

Symptoms:

  • listen tcp :8080: bind: address already in use
  • Server fails to start with port conflict error
  • MCP server can't bind to configured port

Cause: Another process is using the port CIE needs. Common culprits:

  • Previous CIE instance still running
  • Another development server (webpack, vite, etc.)
  • Another MCP server

Solution:

  1. Find process using the port:

    # macOS/Linux
lsof -i :8080
# Shows: COMMAND PID USER ...

# Or with netstat
netstat -tulpn | grep :8080

  2. Kill the process:

    # Replace PID with actual process ID from lsof
kill <PID>

# Or forcefully:
kill -9 <PID>

  3. Change CIE port:

    # .cie/project.yaml
server:
  port: 8081  # Use different port

    Then update MCP config:

    {
  "mcpServers": {
    "cie": {
      "command": "cie",
      "args": ["--mcp", "--port", "8081"]
    }
  }
}

  4. Check for zombie processes:

    # Find all cie processes
ps aux | grep cie

# Kill all cie processes
pkill cie

Note: Most users use stdio mode (cie --mcp) which doesn't require a port. Only network mode needs ports.

Verify:

# Port should be free:
lsof -i :8080
# Should show nothing

cie --mcp
# Should start without port conflict

Related:

Issue: Config Not Found in MCP Mode

Symptoms:

  • config file not found: .cie/project.yaml
  • MCP server starts but has no project context
  • Tools fail with "project not initialized"

Cause: Working directory is not the project root. MCP servers need to run from the directory containing .cie/project.yaml.

Solution:

  1. Check working directory:

    ls .cie/project.yaml
# Should exist

  2. Set cwd in MCP config:

    Claude Code (~/.claude/mcp.json):

    {
  "mcpServers": {
    "cie": {
      "command": "cie",
      "args": ["--mcp"],
      "cwd": "/absolute/path/to/your/project"  // ← Important!
    }
  }
}

    Cursor (run from project root or use shell script):

    # Create wrapper script: ~/bin/cie-mcp.sh
#!/bin/bash
cd /absolute/path/to/your/project
exec cie --mcp "$@"

    Then in .cursor/mcp.json:

    {
  "mcpServers": {
    "cie": {
      "command": "/Users/yourname/bin/cie-mcp.sh"
    }
  }
}

  3. Initialize project if needed:

    cd /path/to/your/project
cie init
cie index

Verify:

cd /path/to/your/project
cie --mcp
# Should show: Project: /path/to/your/project

Related:

Issue: Tools Not Available in AI Assistant

Symptoms:

  • MCP server starts successfully
  • No CIE tools appear in Claude Code/Cursor
  • Assistant doesn't recognize CIE commands
  • Tools list is empty

Cause: Common issues:

  • MCP config syntax error (JSON invalid)
  • Config file in wrong location
  • Tool discovery failed
  • Index not built (tools work but return empty results)

Solution:

  1. Validate MCP config JSON:

    # Check JSON syntax
cat ~/.claude/mcp.json | jq .
# Or for Cursor:
cat .cursor/mcp.json | jq .

# Should parse without errors

  2. Verify config location:

    Claude Code looks in:

    • $PWD/.claude/mcp.json (project-level)
    • ~/.claude/mcp.json (global)

    Cursor looks in:

    • $PWD/.cursor/mcp.json (project-level)

  3. Restart the AI assistant:

    Changes to MCP config require restart:

    • Claude Code: Restart CLI session
    • Cursor: Restart Cursor application

  4. Test tool discovery:

    echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | cie --mcp
# Should return JSON with tools array containing 20+ tools

  5. Check server logs:

    # Claude Code logs (macOS)
tail -f ~/Library/Logs/Claude/mcp.log

# Cursor logs (check Cursor's developer tools)

  6. Verify index exists:

    cie status
# Should show functions indexed

    Tools will load but return empty results if index is empty.

Verify: In Claude Code/Cursor, type:

Use CIE to find functions related to authentication

Assistant should respond with CIE tool results.

Related:

Performance Problems

Issue: Slow Semantic Search

Symptoms:

  • cie_semantic_search takes >10 seconds
  • MCP tool requests timeout
  • Queries fast in CLI but slow in MCP

Cause: Semantic search requires:

  1. Embedding generation for query (50-200ms)
  2. Vector similarity computation across all functions (depends on index size)
  3. Ranking and filtering results

Large indexes (>50k functions) with no filters can be slow.

Solution:

  1. Use filters to narrow search:

    # Slow (searches everything)
cie_semantic_search query="authentication"

# Fast (searches specific path)
cie_semantic_search query="authentication" path_pattern="internal/auth"

  2. Use role filters:

    # Only search handlers (smaller subset)
cie_semantic_search query="user login" role="handler"

# Exclude tests (reduces search space)
cie_semantic_search query="database query" role="source"

  3. Lower result limit:

    # Default returns 10, but still computes similarity for all functions
# Lower limit doesn't help much, but raising it makes it worse:
cie_semantic_search query="handler" limit=5  # Still slow if index is large

  4. Optimize embedding provider:

    Use local Ollama (fastest):

    # .cie/project.yaml
embedding:
  provider: ollama
  ollama:
    url: "http://localhost:11434"
    model: "nomic-embed-text"

    If using OpenAI, use smaller model:

    embedding:
  provider: openai
  openai:
    model: "text-embedding-3-small"  # Faster than 3-large

  5. Exclude large directories from index:

    # .cie/project.yaml
exclude:
  - "vendor/**"
  - "node_modules/**"
  - "test/fixtures/**"
  - "**/*.test.go"

    Then reindex:

    rm -rf .cie/db
cie index

  6. Check index size:

    cie status
# If Functions indexed: >100k, consider excluding more files

Verify:

time cie query --semantic "authentication" --path "internal"
# Should complete in <5 seconds

Related:

Issue: High Memory Usage

Symptoms:

  • CIE process uses >4GB RAM
  • System slows down when querying
  • Out of memory errors during queries

Cause: Large indexes load significant data into memory:

  • Function embeddings (768-dimensional vectors)
  • AST data
  • CozoDB database cache

Solution:

  1. Check index size:

    cie status
du -sh .cie/db

# If >1GB, consider optimization

  2. Reduce indexed functions:

    # .cie/project.yaml - Exclude more aggressively
exclude:
  - "**/*_test.go"          # Exclude all tests
  - "**/*.test.js"
  - "vendor/**"
  - "node_modules/**"
  - "third_party/**"
  - "docs/**"               # Exclude non-code
  - "examples/**"

  3. Use smaller embedding dimension:

    # .cie/project.yaml
embedding:
  provider: ollama
  ollama:
    model: "mxbai-embed-large"  # 1024-dim
    # Instead of nomic-embed-text (768-dim)

    Note: This requires reindexing and may affect search quality.

  4. Limit database cache size:

    # .cie/project.yaml
database:
  cache_size_mb: 512  # Default 1024

  5. Close CIE when not in use:

    # If running MCP server:
pkill cie

# Restart when needed
cie --mcp

Verify:

# Monitor memory usage
ps aux | grep cie
# RSS column shows memory in KB

Related:

Issue: Large Index Size

Symptoms:

  • .cie/db/ directory is >1GB
  • Disk space running low
  • Backup/sync takes long time

Cause: Index stores:

  • Function ASTs (syntax trees)
  • Embeddings (768-1024 dimensions × number of functions)
  • Call graph relationships
  • Metadata

Large projects with many functions create large indexes.

Solution:

  1. Check what's taking space:

    du -sh .cie/db/*
# Identify large components

  2. Exclude test files:

    # .cie/project.yaml
exclude:
  - "**/*_test.go"
  - "**/*.test.js"
  - "**/*.test.ts"
  - "**/*.spec.ts"

    Tests can be 30-50% of codebase.

  3. Exclude generated code:

    exclude:
  - "**/*.pb.go"           # Protobuf generated
  - "**/*.generated.go"
  - "**/mock_*.go"         # Mocks
  - "**/*.gen.ts"

  4. Exclude vendor/dependencies:

    exclude:
  - "vendor/**"
  - "node_modules/**"
  - "third_party/**"

  5. Compact database (doesn't usually help much):

    # Rebuild index (may reduce fragmentation)
rm -rf .cie/db
cie index

  6. Use .cieignore (if available):

    # Similar to .gitignore
echo "**/*_test.go" >> .cieignore
echo "vendor/" >> .cieignore

Typical index sizes:

  • Small project (5k LOC): ~10MB
  • Medium project (50k LOC): ~50-100MB
  • Large project (500k LOC): ~500MB-1GB

Verify:

du -sh .cie/db
# Should decrease after excluding files

Related:

Advanced Debugging

Verbose Logging

Enable debug logging for detailed diagnostics:

# Debug indexing
cie index --debug

# Debug queries
cie query --debug "?[name] := *cie_function{name}"

# Debug MCP server
cie --mcp --debug

Database Inspection

Query CozoDB directly for debugging:

# List all relations (tables)
cie query "?[relations] := show_relations{relations}"

# Show schema for a relation
cie query "?[columns] := show_columns{table: 'cie_function', columns}"

# Count functions by language
cie query "?[language, count] := *cie_function{language}, count = count(*)"

# Find functions without embeddings
cie query "?[name, file] := *cie_function{name, file_path: file, embedding}, is_null(embedding)"

Configuration Debugging

# Show effective configuration
cie config show

# Validate configuration
cie config validate

# Show environment variables
env | grep CIE_

# Test embedding provider
curl -X POST http://localhost:11434/api/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model":"nomic-embed-text","prompt":"test"}'

Performance Profiling

# Profile indexing
time cie index

# Profile query
time cie query --semantic "handler" --limit 10

# Memory profiling (Go)
go tool pprof http://localhost:6060/debug/pprof/heap

Log Files

Check system logs for CIE errors:

macOS:

# System logs
log show --predicate 'process == "cie"' --last 1h

# Claude Code logs
tail -f ~/Library/Logs/Claude/mcp.log

Linux:

# Systemd journal
journalctl -u cie -f

# Syslog
tail -f /var/log/syslog | grep cie

Getting Help

If you can't find a solution here:

1. Search Existing Issues

Check if your problem is already reported:

CIE GitHub Issues

2. Ask in Discussions

For questions and support:

CIE Discussions

3. Report a Bug

If you've found a bug, please report it:

Create New Issue

Include this information:

# System info
cie --version
go version
uname -a

# Configuration
cie config show

# Error log
cie index --debug 2>&1 | tail -100

# Index status
cie status

Quick Reference

Common Commands

# Diagnostics
cie --version
cie status
cie config show
cie config validate

# Index management
cie init                     # Create default config
cie index                    # Index codebase
cie index --debug            # Index with debug logging
cie reset --yes              # Delete indexed data
cie reset --yes && cie index # Full reindex

# Querying
cie query --semantic "query text"
cie query --function "FunctionName"
cie query --text "literal text"

# MCP server
cie --mcp                    # Start MCP server (embedded mode)
cie --mcp --debug            # Start MCP server with debug logging

Common Fixes

Symptom Quick Fix
Library not found Download libcozo_c from CozoDB releases, copy to /usr/local/lib/
No functions indexed Check file extensions (.go, .py, .js, .ts, .tsx)
Ollama connection failed brew install ollama && ollama serve
Index corrupted cie reset --yes && cie index
Slow queries Add path_pattern filter to narrow scope
Empty results Lower min_similarity to 0.5 or try English query
Config not found cd /path/to/project && cie init
Full reset cie reset --yes && cie index

Document Version: 1.0 Last Updated: 2026-01-13 CIE Version: v0.1.0+