Skip to content

Troubleshooting

Jump to bottom Edit New page
Chris edited this page Jun 6, 2026 · 2 revisions

Troubleshooting

Common issues and solutions for db-mcp.

Backend Selection

WASM vs Native

Symptom Cause Solution
Transaction tools return "not available" Using WASM backend Switch to --sqlite-native
Window function tools missing Using WASM backend Switch to --sqlite-native
FTS5 tools return errors Using WASM backend Switch to --sqlite-native
SpatiaLite tools unavailable Using WASM backend Switch to --sqlite-native + --spatialite
Event loop blocking under load WASM synchronous execution Switch to --sqlite-native for production
sqlite_read_query capped at 1,000 rows WASM safety limit Normal behavior — use LIMIT/OFFSET or switch to Native

Rule of thumb: Use --sqlite-native for production. WASM (--sqlite) is for portability and quick prototyping where native compilation isn't available.

Connection Issues

Server Won't Start

Symptom Cause Solution
Cannot find module 'better-sqlite3' Native bindings not compiled Run npm rebuild better-sqlite3 or use Docker
SQLITE_CANTOPEN: unable to open database Database path doesn't exist Create the directory first, or use :memory:
SQLITE_READONLY: attempt to write Database file is read-only Check file permissions: chmod 644 database.db
Server starts but no tools appear Missing --sqlite or --sqlite-native Specify a database path in CLI args

Docker Networking

Symptom Cause Solution
Container can't access database file Volume not mounted Add -v /host/path:/app/data
Port 3000 not accessible Not bound to all interfaces Add --server-host 0.0.0.0
Health check fails from outside container Binding to localhost inside container Use --server-host 0.0.0.0

Tool Filtering

Debugging Filters

Symptom Cause Solution
Expected tools not appearing Wrong filter expression Check server_info tool output for active groups
Too many tools overwhelming IDE No filter applied Use --tool-filter codemode (recommended)
Shortcut doesn't include expected group Shortcut has fixed composition Use explicit groups: --tool-filter core,json,stats
+group syntax not adding tools Missing base filter Start with a shortcut: --tool-filter starter,+stats

Tip: Use server_info to see exactly which tools are active in your current configuration.

Extension Loading

SpatiaLite

Symptom Cause Solution
Extension loading not supported WASM backend doesn't support extensions Switch to --sqlite-native
Cannot load SpatiaLite Missing extension binary Set SPATIALITE_PATH to the binary location
SpatiaLite works on AMD64 but not ARM64 Not pre-installed on ARM64 Docker image Install manually or use AMD64 image

CSV Extension

Symptom Cause Solution
csv extension not loaded Missing --csv flag or binary Add --csv flag and set CSV_EXTENSION_PATH
CSV table creation fails Invalid file path in container Ensure CSV file is accessible inside the container via volume mount

OAuth Issues

Symptom Cause Solution
401 Unauthorized on all requests Missing or expired token Check token expiry and refresh
403 Forbidden on specific tools Token missing required scope Add the required scope (see OAuth & Security)
JWKS discovery fails Issuer URL unreachable Verify --oauth-issuer URL is accessible from the server
Clock skew errors Server time drift Increase --oauth-clock-tolerance (default: 60s)

Code Mode

Symptom Cause Solution
Blocked pattern detected Code contains restricted patterns Remove eval(), require(), import(), or similar
Execution timeout Code exceeded 30s limit Optimize code or reduce query scope
Rate limit exceeded More than 10 executions/minute Wait and retry, or reduce execution frequency
Result too large Output exceeds CODE_MODE_MAX_RESULT_SIZE Filter data in code, or increase limit via env var
Method not available Readonly mode or wrong backend Check sqlite.help() for available methods
isolated-vm build fails Missing native build tools Use Docker (pre-built), or install build essentials

Performance

General Tips

  • Use Native backend for production — WASM blocks the event loop
  • Enable WAL mode — sqlite_wal tool can enable Write-Ahead Logging for concurrent reads
  • Run ANALYZE — sqlite_analyze updates query planner statistics
  • Check indexes — sqlite_index_audit finds missing or redundant indexes
  • Use Code Mode — reduces token overhead by 70–90% vs individual tool calls
  • Set tool filters — fewer registered tools = faster tools/list response

Database Size

  • Run VACUUM — sqlite_vacuum reclaims space after large deletes
  • Check fragmentation — sqlite_stats_detect_bloat identifies fragmented tables
  • Monitor storage — sqlite_dbstat provides per-table size breakdown

Build Issues

Symptom Cause Solution
TypeScript compilation errors Wrong Node.js version Use Node.js 24+ (check engines in package.json)
better-sqlite3 build fails Missing C++ build tools Install build-essential (Linux), Xcode CLT (macOS), or use Docker
isolated-vm build fails Incompatible platform Use Docker or install build essentials
Tests fail with SQLITE_ERROR SQLite version mismatch Ensure SQLite supports features used in tests

Getting Help

  1. Check this page — most common issues are covered above
  2. Search the Wiki — comprehensive documentation
  3. Try AI Wiki Search — natural language search across all docs
  4. Review GitHub Issues — existing bug reports and feature requests
  5. Open a new issue — include environment details, steps to reproduce, and error messages
  6. Email — admin@adamic.tech for security vulnerabilities (see Security Policy)
Add a custom footer

SQLite MCP Server

🏠 Home

📣 Updates

🚀 Getting Started

🔌 SQLite

🤖 AI Integration

🔐 Enterprise

🔗 External Links

Clone this wiki locally