Troubleshooting

Troubleshooting

Common issues and solutions.

Native Module Issues (v1.0+)

Native module not loading

Symptoms: Drift falls back to TypeScript (slower), or shows "native not available"

Solutions:

1. Check native module status:

   drift --version --verbose
   # Should show: Native module: ✓ available

2. Rebuild native modules:

   npm rebuild @drift/native

3. Ensure you have build tools:

   • macOS: xcode-select --install
   • Ubuntu: sudo apt-get install build-essential
   • Windows: Install Visual Studio Build Tools

4. Check Node.js version (18-20 recommended):

   node --version
   # v18.x or v20.x recommended

ESM module loading errors

Symptoms: require is not defined or similar ESM errors

Solutions:

1. This was fixed in v1.0.0. Update to latest:

   npm install -g driftdetect@latest

2. If using custom setup, ensure createRequire is used for native modules

---

Installation Issues

npm install fails

Symptoms: Tree-sitter native modules fail to build

Solutions:

1. Ensure you have build tools installed:

   • macOS: xcode-select --install
   • Ubuntu: sudo apt-get install build-essential
   • Windows: Install Visual Studio Build Tools

2. Try with Node.js 18 or 20 (not 22+):

   nvm use 18
   npm install -g driftdetect

3. Clear npm cache:

   npm cache clean --force
   npm install -g driftdetect

npx driftdetect hangs

Solutions:

1. Use global install instead:

   npm install -g driftdetect
   drift init

2. Clear npx cache:

   rm -rf ~/.npm/_npx
   npx driftdetect init

---

Scanning Issues

Scan takes too long

Symptoms: Scan runs for 10+ minutes

Solutions:

1. Check .driftignore excludes large directories:

   node_modules/
   dist/
   build/
   .git/
   vendor/

2. Scan a subdirectory:

   drift scan src/

3. Use timeout:

   drift scan --timeout 600000

4. Use incremental scanning:

   drift scan --incremental

No patterns found

Symptoms: drift status shows 0 patterns

Solutions:

1. Ensure you're scanning source files:

   drift scan src/

2. Check language is supported:

   drift parser --test

3. Lower confidence threshold:

   // .drift/config.json
   {
     "patterns": {
       "minConfidence": 0.3
     }
   }

4. Check file extensions are recognized:

   • TypeScript: .ts, .tsx
   • Python: .py
   • Java: .java
   • C#: .cs
   • PHP: .php

Scan fails with error

Symptoms: Scan crashes or exits with error

Solutions:

1. Run with verbose output:

   drift scan --verbose

2. Check for syntax errors in your code (Drift handles most, but some crash parsers)

3. Try scanning specific files:

   drift scan src/api/

4. Report the issue with the error message: https://github.com/dadbodgeoff/drift/issues

---

MCP Issues

MCP server not connecting

Symptoms: AI agent can't find Drift tools

Solutions:

1. Verify config file location:

   • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
   • Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json

2. Check JSON syntax:

   {
     "mcpServers": {
       "drift": {
         "command": "npx",
         "args": ["-y", "driftdetect-mcp"]
       }
     }
   }

3. Restart the AI client after config changes

4. Test MCP server manually:

   npx driftdetect-mcp
   # Should start without errors

"Scan required" errors

Symptoms: MCP tools return "scan required" error

Solutions:

1. Run initial scan:

   cd your-project
   drift init
   drift scan

2. Ensure .drift/ directory exists and has data

3. Check you're in the right directory

Slow MCP responses

Symptoms: AI takes long time to get Drift data

Solutions:

1. First call is always slower (loading data)

2. Use drift_status first (lightweight)

3. For large codebases, pre-build call graph:

   drift callgraph build

4. Enable caching (default):

   {
     "mcp": {
       "cache": {
         "enabled": true
       }
     }
   }

---

Call Graph Issues

Call graph not building

Symptoms: drift callgraph build fails or shows 0 functions

Solutions:

1. Ensure source files are being scanned:

   drift scan --verbose

2. Check parser status:

   drift parser --test

3. Try building for specific directory:

   drift callgraph build src/

Reachability returns nothing

Symptoms: drift callgraph reach returns empty results

Solutions:

1. Ensure call graph is built:

   drift callgraph status

2. Check the location format:

   # File:line format
   drift callgraph reach src/api/users.ts:42
   
   # Function name
   drift callgraph reach handleLogin

3. Increase max depth:

   drift callgraph reach src/api/users.ts:42 --max-depth 20

---

Dashboard Issues

Dashboard won't start

Symptoms: drift dashboard fails to open

Solutions:

1. Check port availability:

   drift dashboard --port 3001

2. Try without auto-open:

   drift dashboard --no-browser
   # Then open http://localhost:3000 manually

3. Check for errors:

   drift dashboard --verbose

Dashboard shows no data

Symptoms: Dashboard opens but is empty

Solutions:

1. Run a scan first:

   drift scan
   drift dashboard

2. Check .drift/ directory has data

---

CI Issues

drift check always passes

Symptoms: CI never fails even with violations

Solutions:

1. Use --ci flag:

   drift check --ci --fail-on warning

2. Ensure patterns are approved:

   drift approve --category api --yes
   drift check --ci

drift check always fails

Symptoms: CI fails on every run

Solutions:

1. Lower fail threshold:

   drift check --ci --fail-on error  # Only fail on errors

2. Ignore specific patterns:

   drift ignore <pattern-id>

3. Check what's failing:

   drift check --format json

---

Getting Help

Reporting Issues

Include in your bug report:

1. Drift version: drift --version
2. Node.js version: node --version
3. Operating system
4. Error message (full output)
5. Steps to reproduce

Community

• GitHub Issues
• GitHub Discussions