Troubleshooting

Common issues and solutions for the vCon MCP Server.

Installation Issues

Error: "Cannot find module 'dotenv'"

Symptom:

Error: Cannot find module 'dotenv'

Cause: Dependencies not installed

Solution:

npm install

Error: "ENOENT: no such file or directory, open 'dist/index.js'"

Symptom:

Error: ENOENT: no such file or directory, open '/path/to/vcon-mcp/dist/index.js'

Cause: Project not built

Solution:

npm run build

Error: "Invalid Supabase URL"

Symptom:

Error: Invalid Supabase URL or API key

Cause: Missing or incorrect environment variables

Solution:

Check .env file exists:
```
cat .env
```

Verify format (no quotes needed):

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=eyJ...

Get correct values from Supabase:
- Dashboard → Settings → API
- Copy Project URL and anon public key

Database Issues

Error: "relation 'vcons' does not exist"

Symptom:

Error: relation "vcons" does not exist

Cause: Database migrations not applied

Solution:

Option A: Using Supabase CLI

npx supabase db push

Option B: Manual via Dashboard

Go to Supabase SQL Editor
Run each migration from supabase/migrations/ in order

Verify tables created:

SELECT table_name FROM information_schema.tables 
WHERE table_schema = 'public';

Error: "permission denied for table vcons"

Symptom:

Error: permission denied for table vcons

Cause: RLS policies not configured or using wrong key

Solution:

Check you're using the correct key (anon key, not service role key for testing)

Verify RLS policies exist:

SELECT * FROM pg_policies WHERE tablename = 'vcons';

If missing, run RLS migration:

# In Supabase SQL Editor
-- Run: supabase/migrations/003_rls_policies.sql

Database connection timeout

Symptom:

Error: Connection timeout

Cause: Network issues or invalid URL

Solution:

Test connection:

curl "https://your-project.supabase.co/rest/v1/" \
  -H "apikey: your-anon-key"

Should return 200 OK

Check Supabase project is active (not paused)
Verify URL format: https://PROJECT_ID.supabase.co

Claude Desktop Issues

Claude Desktop doesn't show vCon tools

Symptom: Claude doesn't list vCon tools when asked "What tools do you have?"

Checklist:

✅ Built the project

npm run build
ls -la dist/index.js  # Should exist

✅ Used absolute path in config

# Get absolute path
cd /path/to/vcon-mcp && pwd
# Use: /full/path/to/vcon-mcp/dist/index.js

✅ Restarted Claude Desktop completely
- Quit Claude Desktop (not just close window)
- Reopen Claude Desktop
- Start new conversation

✅ .env file in project root

ls -la /path/to/vcon-mcp/.env  # Should exist

✅ Valid Supabase credentials
```
cat .env  # Check values
```

Debug Steps:

Test server directly:
```
node dist/index.js
```
Should output MCP initialization messages Press Ctrl+C to stop
Check config syntax:
```
# macOS
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
Verify valid JSON (no trailing commas, proper brackets)
Check logs:
- Open Claude Desktop
- Help → View Logs
- Look for MCP server errors

Error: "spawn node ENOENT"

Symptom:

Error: spawn node ENOENT

Cause: Node.js not in PATH for Claude Desktop

Solution:

macOS:

{
  "mcpServers": {
    "vcon": {
      "command": "/usr/local/bin/node",  // Full path to node
      "args": ["/absolute/path/to/vcon-mcp/dist/index.js"]
    }
  }
}

Find node path:

which node

Claude can't find vCons

Symptom:

No vCons found

Cause: Empty database

Solution:

Create test vCon:

Create a vCon with subject "Test" and party "Alice"

Verify in database:

SELECT uuid, subject FROM vcons;

Runtime Errors

Error: "vCon validation failed"

Symptom:

Error: vCon validation failed: [validation details]

Cause: Invalid vCon data structure

Solution:

Check error message for specific field
Verify required fields:
- vcon version (e.g., "0.3.0")
- uuid (valid UUID)
- created_at (ISO 8601 timestamp)
- At least one party

Use valid values:

{
  vcon: "0.3.0",
  uuid: "valid-uuid-here",
  created_at: "2025-01-15T10:00:00Z",
  parties: [{
    name: "Alice"
  }]
}

Error: "Analysis vendor required"

Symptom:

Error: Analysis must have vendor field

Cause: Missing required vendor field in analysis

Solution:

Always include vendor when adding analysis:

Add transcript analysis with vendor "OpenAI"

Error: "Invalid UUID format"

Symptom:

Error: Invalid UUID format

Cause: Malformed UUID

Solution:

Use valid UUID v4 format:

abc12345-1234-1234-1234-123456789abc

Get UUID from vCon list:

Show me recent vCons

Search Issues

Semantic search not working

Symptom:

Error: Semantic search requires embeddings

Cause: Embeddings not configured or generated

Solution:

Enable pgvector extension:
```
CREATE EXTENSION IF NOT EXISTS vector;
```

Run vector migrations:

# In Supabase SQL Editor
-- Run: supabase/migrations/005_vector_extension.sql
-- Run: supabase/migrations/006_embeddings_table.sql

Add OpenAI API key:

echo "OPENAI_API_KEY=sk-your-key" >> .env

Generate embeddings:

npm run scripts/generate-embeddings-v2.ts

Search returns no results

Symptom: Search finds nothing when data exists

Cause: Various possibilities

Solutions:

Check data exists:
```
Show me all vCons
```
Try simpler search:
```
Find vCons from the last month
```
Check search mode:
- Basic search: subject/party/dates only
- Keyword search: full-text in dialog/analysis
- Semantic search: requires embeddings
Verify content is searchable:
- Dialog must have encoding: "none" for keyword search
- Attachments not included in search

Performance Issues

Slow queries

Symptom: Queries take >2 seconds

Cause: Missing indexes or large dataset

Solution:

Check indexes exist:

SELECT * FROM pg_indexes WHERE tablename IN ('vcons', 'dialog', 'analysis');

Run index migration:

# In Supabase SQL Editor
-- Run: supabase/migrations/002_indexes.sql

Analyze tables:

ANALYZE vcons;
ANALYZE dialog;
ANALYZE analysis;

Check database stats:
```
Show me database performance stats
```

Out of memory

Symptom:

Error: JavaScript heap out of memory

Cause: Large dataset operations

Solution:

Increase Node.js memory:

node --max-old-space-size=4096 dist/index.js

Use pagination in searches:
```
Find first 10 vCons from January
```
Use resources for simple reads:
```
Read vcon://v1/vcons/abc-123/metadata
```

Testing Issues

Tests fail with "database connection error"

Symptom:

Error: Database connection failed

Cause: Test environment not configured

Solution:

Create .env.test file:
```
cp .env .env.test
```

Use test database (separate from production):

SUPABASE_URL=https://test-project.supabase.co
SUPABASE_ANON_KEY=test-key

Run migrations on test database
Run tests:
```
npm test
```

Tests pass but code fails

Symptom: Tests succeed but actual usage fails

Cause: Different environment (test vs production)

Solution:

Verify .env vs .env.test settings
Check both databases have same schema
Test with production credentials (carefully)
Add integration tests:
```
npm run test:integration
```

Plugin Issues

Plugin not loading

Symptom:

Error: Could not load plugin: ./my-plugin.js

Cause: Plugin path or format incorrect

Solution:

Verify plugin path:
```
ls -la ./my-plugin.js  # Should exist
```

Check plugin format:

export default class MyPlugin {
  name = 'my-plugin';
  version = '1.0.0';
  // ... implementation
}

Check environment variable:
```
echo $VCON_PLUGINS_PATH
```
Test plugin loading:
```
node -e "require('./my-plugin.js')"
```

Build Issues

TypeScript compilation errors

Symptom:

Error: TypeScript compilation failed

Solution:

Check TypeScript version:
```
npx tsc --version  # Should be 5.x
```

Clean and rebuild:

rm -rf dist node_modules
npm install
npm run build

Fix type errors shown in output

Missing dependencies

Symptom:

Error: Cannot find module '@modelcontextprotocol/sdk'

Solution:

npm install

If persists:

rm -rf node_modules package-lock.json
npm install

Getting More Help

Debug Mode

Enable detailed logging:

LOG_LEVEL=debug node dist/index.js

Verbose Tests

npm test -- --reporter=verbose

Check System Status

# Node.js
node --version

# npm
npm --version

# Dependencies
npm list --depth=0

# Build status
ls -la dist/

# Environment
cat .env

Report Issues

If you can't resolve an issue:

Search existing issues: GitHub Issues
Create new issue with:
- Error message (full text)
- Steps to reproduce
- Environment details (OS, Node.js version, etc.)
- Relevant config (sanitized, no keys)
Ask in discussions: GitHub Discussions

Quick Fixes

"It just doesn't work"

Try this sequence:

# 1. Clean everything
rm -rf node_modules dist

# 2. Reinstall
npm install

# 3. Rebuild
npm run build

# 4. Test
npm test

# 5. Verify env
cat .env

# 6. Test server
node dist/index.js
# Should see initialization messages
# Press Ctrl+C

# 7. Restart Claude Desktop
# Quit completely and reopen

Reset to fresh state

# Backup first!
cp -r vcon-mcp vcon-mcp.backup

# Clean
git clean -fdx
git reset --hard

# Reinstall
npm install
npm run build

# Reconfigure
cp .env.example .env
# Edit .env with your credentials

Still stuck? Ask for help →

Found a bug? Report it →

PreviousDatabase Tools NextFAQ

Last updated 22 days ago

Good afternoon

Installation Issues

Error: "Cannot find module 'dotenv'"

Error: "ENOENT: no such file or directory, open 'dist/index.js'"

Error: "Invalid Supabase URL"

Database Issues

Error: "relation 'vcons' does not exist"

Error: "permission denied for table vcons"

Database connection timeout

Claude Desktop Issues

Claude Desktop doesn't show vCon tools

Error: "spawn node ENOENT"

Claude can't find vCons

Runtime Errors

Error: "vCon validation failed"

Error: "Analysis vendor required"

Error: "Invalid UUID format"

Search Issues

Semantic search not working

Search returns no results

Performance Issues

Slow queries

Out of memory

Testing Issues

Tests fail with "database connection error"

Tests pass but code fails

Plugin Issues

Plugin not loading

Build Issues

TypeScript compilation errors

Missing dependencies

Getting More Help

Debug Mode

Verbose Tests

Check System Status

Report Issues

Quick Fixes

"It just doesn't work"

Reset to fresh state