Skip to main content

​
Start Here: info and doctor

Before diving into specific issues, run these two commands. They catch most setup problems immediately. 
sdl-mcp info
sdl-mcp info shows the resolved config path, active log file, log fallback status, LadybugDB availability, and native-addon state in one place. 
sdl-mcp doctor --log-level debug
sdl-mcp doctor validates your runtime, config, database, grammars, and repo access — with debug-level output for detailed diagnostics.

​
Common Issues

SDL-MCP cannot locate a configuration file at startup.Fixes:
  • Run sdl-mcp init to generate a config file in the current directory
  • Pass an explicit config path with -c /path/to/config.json
  • Set the SDL_CONFIG (or SDL_CONFIG_PATH) environment variable to point to your config file
  • Set SDL_CONFIG_HOME to control the default global config directory
Errors loading tree-sitter grammars or native .node modules on install or startup.Fixes:
  • Reinstall all dependencies: npm install
  • If native modules are stale or were built for a different Node.js version: npm rebuild
SDL-MCP cannot read the repository path specified in config.Fixes:
  • Verify that rootPath in your config exists and is readable
  • Use absolute paths in config rather than relative paths
  • In container or CI environments, confirm that the repo directory is mounted and accessible
Initial or incremental indexing takes longer than expected.Fixes:
  • Reduce indexed languages to only those you need in your config
  • Add more ignore glob patterns to skip generated files, node_modules, build artifacts, etc.
  • Lower maxFileBytes to skip very large files
  • Tune indexing.concurrency to match your machine’s core count
  • Switch to the native Rust engine for faster pass-1 extraction: set indexing.engine: "rust" in config
Symbols returned by search or slice tools do not reflect recent code changes.Fixes:
  • Run sdl-mcp index from the CLI to trigger a full re-index
  • Or call sdl.index.refresh with incremental: true from an MCP tool
  • Enable watcher mode to keep the index current automatically: sdl-mcp index --watch
Indexing completes without errors but symbol searches return no results.Fixes:
  • Confirm the rootPath in config points to the correct repository root
  • Verify the languages you want indexed are listed under languages in config
  • Check that your ignore patterns are not accidentally excluding your source files
  • Run sdl-mcp doctor to check for any grammar or adapter failures
  • Inspect the log file for parse errors on specific file types
.js files are not indexed even though javascript is listed in languages.This is expected behavior. When both foo.ts and foo.js exist at the same path, the scanner excludes the .js file to avoid indexing compiled output alongside source.Fix: If the .js file is hand-written source (not compiled output), remove or rename the corresponding .ts file.
The MCP server starts but the connected agent does not call SDL-MCP tools.Fixes:
  • Ensure the agent is configured to connect to sdl-mcp serve --stdio
  • Validate the generated client config by running sdl-mcp init --client <name> (e.g., --client claude-code)
  • Run sdl-mcp info to confirm the resolved config path, log file path, and native-addon status
  • If your agent enforces explicit tool approval, add SDL-MCP tools to the approved list
  • Enable SDL_CONSOLE_LOGGING=true to mirror logs to stderr during manual debugging
The agent cannot connect to the MCP server, or connections drop unexpectedly.stdio is the default transport for local agents (Claude Code, Cursor, Windsurf, etc.):
sdl-mcp serve --stdio
HTTP/SSE is used for multi-agent or networked setups:
sdl-mcp serve --http
Fixes:
  • Confirm the transport flag matches your client’s expected transport type
  • For HTTP, verify the host and port in the client config match the server’s listen address
  • For multi-agent HTTP setups, the session limit is 8 concurrent sessions; additional connections are rejected until a slot frees up
  • Check the log file for connection-level errors
File watching is enabled but re-indexing does not trigger on changes, or the watcher fails to start.Use the --no-watch fallback and trigger manual refreshes until the underlying issue is resolved:
sdl-mcp serve --no-watch
sdl-mcp index  # run manually after changes
Platform-specific causes:Windows — antivirus / endpoint locks
  • Symptom: frequent watcher errors, delayed or missing re-index events
  • Cause: file handles held by antivirus or endpoint scanning tools
  • Fix: exclude your repo path and SDL-MCP DB path from scanning; fall back to --no-watch
Linux — inotify limits
  • Symptom: watcher fails to start on large repos
  • Cause: low fs.inotify.max_user_watches or max_user_instances
  • Fix: increase inotify limits via sysctl, add stronger ignore patterns, or cap load with indexing.maxWatchedFiles
Network drives / remote filesystems
  • Symptom: inconsistent or missing watch events
  • Cause: non-local filesystems may not emit reliable file notifications
  • Fix: run SDL-MCP on a local clone or worktree; disable watch mode and use periodic incremental indexing
Queries are slow, or the server uses high memory on large repositories.Fixes:
  • Narrow the indexed language list and add aggressive ignore patterns for non-source directories
  • Use indexing.engine: "rust" for faster multi-threaded pass-1 extraction
  • Tune indexing.concurrency to control parallelism
  • For large repos, run sdl-mcp index during off-hours and use incremental mode (incremental: true) for updates
  • Reduce maxFileBytes to skip binary or generated large files
  • Use the gateway mode (tools.gateway: true) to reduce tools/list overhead by 81%
Log warning: "Rust engine returned null, falling back to TypeScript engine"The native .node addon was not built for your current platform or Node.js version.Fixes:
  • Build the native addon: npm run build:native from the sdl-mcp directory
  • Verify the Rust toolchain is installed: rustc --version
  • Ensure the Node.js major version matches the one used during the build
  • Confirm that native/*.node exists after the build
  • If you do not need the Rust engine, explicitly configure the TypeScript fallback: indexing.engine: "typescript"
The TypeScript engine (tree-sitter) is fully supported and produces identical results. The Rust engine is an optional performance enhancement.
Error about a database lock or “directory in use” at startup.The database lock was not released — typically because a previous SDL-MCP process crashed or another process still has the DB open.Fixes:
  • Ensure no other sdl-mcp serve or sdl-mcp index process is running
  • Delete the lock file inside the .lbug database directory (the directory named in graphDatabase.path), then restart
  • If the database is corrupted, delete the entire .lbug directory and re-run sdl-mcp index to rebuild from source
Intermittent query failures or "transaction conflict" errors when multiple agents connect.LadybugDB allows concurrent reads but serializes writes. Long-running write transactions can conflict with concurrent queries.Fixes:
  • Use HTTP transport (sdl-mcp serve --http) for multi-agent setups — sessions are isolated
  • Avoid running sdl-mcp index while agents are actively querying; prefer indexing during quiet periods or using incremental mode
  • If errors persist, restart the server to clear stale transaction state
Error "not compatible with the current graph engine" at startup after an upgrade.The LadybugDB schema version changed between releases in a way that cannot be migrated automatically.Fixes:
  • Restart SDL-MCP once to allow any pending forward migrations to run
  • If the database is still reported as incompatible, delete the .lbug database directory and re-run sdl-mcp index to rebuild from source
Migrating older graph databases in-place is not supported. Deleting the .lbug directory and re-indexing is the supported recovery path.
Warning "Failed to load ONNX runtime" or semantic search returns no results.The onnxruntime-node native binary is missing or incompatible with your platform or Node.js version.Fixes:
  • Recompile for your platform: npm rebuild onnxruntime-node
  • On Windows, ensure the Visual C++ Redistributable is installed
  • If the ONNX binary cannot be built, disable semantic features: set semantic.enabled: false in config to fall back to text-based search
  • Run sdl-mcp doctor for ONNX-specific diagnostics
First run hangs or errors during model download (e.g., nomic-embed-text-v1.5).Network restrictions or proxy settings are blocking the model download (~138 MB).Fixes:
  • Ensure outbound HTTPS access to the Hugging Face model hub is allowed
  • Configure proxy via the HTTPS_PROXY environment variable if needed
  • Consider using the smaller default model (all-MiniLM-L6-v2, ~22 MB) which may already be cached
No logs appear in the configured location, or logs appear under a temp directory.The path configured for SDL_LOG_FILE or the derived default is not writable.Fixes:
  • Run sdl-mcp info and inspect the logging.path and logging.fallbackUsed fields
  • Fix permissions on the log directory, or set SDL_LOG_FILE to a writable path
  • Set SDL_CONSOLE_LOGGING=true temporarily to mirror logs to stderr while fixing file logging

​
Debug Commands

sdl-mcp version
sdl-mcp info
sdl-mcp doctor --log-level debug
sdl-mcp index --repo-id <repo-id>
sdl-mcp serve --stdio

Build docs developers (and LLMs) love

Get started for freeTalk to us