Troubleshooting¶

Solutions to common issues with Concept-RAG.

Installation Issues¶

"node: command not found"¶

Node.js not installed or not in PATH.

Ubuntu/DebianmacOSManual

sudo apt update
sudo apt install nodejs npm

brew install node

Download from nodejs.org

"npm install" fails¶

Clear cache and reinstall:

rm -rf node_modules package-lock.json
npm cache clean --force
npm install

Python/NLTK not found¶

# Install NLTK
pip3 install nltk

# Download WordNet data
python3 -c "import nltk; nltk.download('wordnet'); nltk.download('omw-1.4')"

# Verify
python3 -c "from nltk.corpus import wordnet as wn; print(f'✅ WordNet: {len(list(wn.all_synsets()))} synsets')"

Seeding Problems¶

"Error: OPENROUTER_API_KEY not set"¶

# Create .env file
echo "OPENROUTER_API_KEY=your_key_here" > .env

# Or export directly
export OPENROUTER_API_KEY="your_key_here"

# Get key at: https://openrouter.ai/keys

"No PDF files found"¶

Check your paths

# Verify directory exists
ls -la ~/Documents/pdfs

# Find PDFs
find ~/Documents/pdfs -name "*.pdf"

# Use absolute path
npx tsx hybrid_fast_seed.ts \
  --dbpath ~/.concept_rag \
  --filesdir /absolute/path/to/pdfs

PDF parsing failed¶

Possible causes:

Corrupted PDF
Password-protected PDF
Unusual encoding

Solutions:

OCR fallback handles scanned PDFs automatically
Re-save PDF using another tool
Check if PDF opens in a reader
Try converting to PDF/A format

Out of memory during seeding¶

# Increase Node.js memory
NODE_OPTIONS="--max-old-space-size=4096" npx tsx hybrid_fast_seed.ts \
  --dbpath ~/.concept_rag \
  --filesdir ~/docs

Or process documents in smaller batches.

Search Issues¶

No results found¶

Verify documents are indexed:
```
npx tsx scripts/health-check.ts
```
Try different search tools:
concept_search → broad_chunks_search
catalog_search → chunks_search
Check query phrasing: | ❌ Bad | ✅ Good | |--------|---------| | "show me innovation stuff" | "innovation" | | "stuff about AI" | "machine learning applications" |

Search returns irrelevant results¶

Use the right tool for your goal:

Goal	Use	Not
Find by concept	`concept_search`	`broad_chunks_search`
Search in document	`chunks_search`	`catalog_search`

See API Reference for tool documentation.

Slow search queries¶

# Rebuild indexes
npx tsx scripts/rebuild_indexes.ts

# Check database size
du -sh ~/.concept_rag

# Restart MCP client

MCP Integration¶

MCP server not connecting¶

Checklist

✅ Paths are absolute (not relative)
✅ Project is built (npm run build)
✅ Database path exists
✅ Client restarted after config changes

Verify paths:

# Get absolute path
cd /path/to/concept-rag && pwd

# Check database
ls -la ~/.concept_rag

# Check build
ls -la dist/conceptual_index.js

MCP tools not appearing¶

Check configuration syntax:

python3 -m json.tool ~/.cursor/mcp.json

Test with MCP Inspector:

npx @modelcontextprotocol/inspector \
  dist/conceptual_index.js \
  ~/.concept_rag

Check for conflicting servers — remove others temporarily

Permission denied errors¶

# Fix permissions
chmod +x /path/to/concept-rag/dist/conceptual_index.js
chmod -R 755 ~/.concept_rag

# Fix ownership
sudo chown -R $USER:$USER ~/.concept_rag

Data Issues¶

Incomplete catalog records¶

Symptoms: - "Mapped X/Y sources" where X < Y - Duplicate source path warnings

Solution:

npx tsx hybrid_fast_seed.ts \
  --filesdir ~/Documents \
  --auto-reseed

Missing concepts for document¶

# Re-seed with auto-reseed flag
npx tsx hybrid_fast_seed.ts --dbpath ~/.concept_rag --filesdir ~/docs --auto-reseed

# Or full re-seed
npx tsx hybrid_fast_seed.ts --dbpath ~/.concept_rag --filesdir ~/docs --overwrite

Error Messages¶

Error	Solution
`Cannot find module '@lancedb/lancedb'`	`npm install && npm run build`
`ENOENT: no such file or directory`	Create directory: `mkdir -p ~/.concept_rag`
`Table not found: catalog`	Seed the database first
`spawn python3 ENOENT`	Install Python or add to PATH

Debug Mode¶

Enable verbose logging:

export LOG_LEVEL=debug
npx tsx hybrid_fast_seed.ts --dbpath ~/.concept_rag --filesdir ~/docs

Check log files:

# View latest log
ls -t logs/seed-*.log | head -1 | xargs cat

# Search for errors
grep ERROR logs/seed-*.log

Quick Fixes Checklist¶

When something doesn't work, try in order:

[ ] Restart Claude/Cursor
[ ] Rebuild: npm run build
[ ] Check paths are absolute
[ ] Verify API key is set
[ ] Test with MCP Inspector
[ ] Rebuild indexes: npx tsx scripts/rebuild_indexes.ts
[ ] Check database exists: ls -la ~/.concept_rag
[ ] Verify Python/NLTK installed
[ ] Clear and reinstall: rm -rf node_modules && npm install