🛠️ NakshAstraMCP — Troubleshooting Guide

Recovery Hub: Diagnose and resolve connectivity problems, indexing delays, port conflicts, and environment configuration issues.

📋 Table of Contents

  1. First Step — Run the Doctor
  2. Common Issues & Fixes
  3. Log Locations & Streaming
  4. Getting Further Help

🩺 First Step — Run the Doctor

For any configuration, permission, or library anomaly — always start here:

nakshastramcp doctor

The doctor runs 13 automated pre-flight checks covering: Python runtime integrity, FTS5 availability, Tree-sitter API health, grammar integrity hashes, FlashRank model cache status, Tantivy engine, port availability, disk space, and Windows Long Path settings.

Review the output. Fix any checks marked FAIL ❌ (critical failures) before investigating further. See the complete doctor reference in the Setup Guide → Doctor Pre-Flight Diagnostics Reference.

🛠️ Common Issues & Fixes

1. JSON Parsing Error: invalid character '_' looking for beginning of value

Symptom: Your AI client (e.g., Claude Desktop, Cursor, VS Code) reports a JSON parsing error when connecting to the server.

Root Cause: The MCP client uses stdio transport and expects pure JSON-RPC frames on stdout. When the transport flag is missing or wrong, the server may print diagnostic banners or startup text onto stdout, which the client tries to parse as JSON — and fails.

Fix: Explicitly add --transport stdio to your IDE’s MCP configuration:

{
  "mcpServers": {
    "nakshastramcp": {
      "command": "nakshastramcp",
      "args": ["start", "--transport", "stdio"]
    }
  }
}

[!NOTE] In stdio mode, all startup banners and info messages are routed to stderr, keeping stdout clean for JSON-RPC communication.

2. Dual Transport Bridge Conflict: Port 2102 in Use

Symptom: The host stdio IDE connection starts successfully, but secondary follower clients cannot reach the HTTP bridge. Logs show Port 2102 is already in use.

Root Cause: Another service or an orphaned background NakshAstraMCP process is already listening on port 2102.

Fix Option A — Kill the conflicting process:

# Windows: Find and kill the process using port 2102
netstat -ano | findstr :2102
taskkill /PID <PID> /F

# macOS / Linux
lsof -ti :2102 | xargs kill -9

Fix Option B — Use a different port:

nakshastramcp start --port 3000

Then update your follower clients to target http://127.0.0.1:3000/mcp.

3. Missing or Stale Search Results

Symptom: The AI assistant returns incomplete context or cannot find a recently added function, class, or file.

Resolution:

  1. Verify the workspace is registered and indexing has completed: 
    nakshastramcp status
  2. Check if your .mcpignore file is accidentally excluding the files: 
    # Open the mcpignore in your project root
cat .\.mcpignore
  3. Force a complete re-index: 
    nakshastramcp start --workspace . --force
  4. If using the real-time watcher, confirm it’s active (check the logs): 
    nakshastramcp logs --lines 30

4. Elevated Memory Consumption

Symptom: Background processes use significantly more than expected RAM on massive codebases (> 1 GB).

Resolution:

  1. Create or expand your .mcpignore to exclude large binary directories, virtual environments, and output logs: 
    dist/
build/
node_modules/
.venv/
__pycache__/
*.csv
*.parquet
*.db
  2. Trigger immediate garbage collection: 
    nakshastramcp gc
  3. Lower the maximum number of simultaneous active workspace contexts in config.toml: 
    mem_lru_size = 3
  4. Lower the Memory Guard threshold to trigger cleanups sooner: 
    mem_threshold_mb = 512

5. Grammar Addon Compilation Failures

Symptom: Running nakshastramcp provision --lang rust --lib ./tree_sitter_rust.dll returns validation or compilation errors.

Resolution:

6. Server Fails to Start — “Already Running” Error

Symptom: nakshastramcp start exits with ERROR: NakshAstraMCP is already running (PID: XXXX).

Root Cause: A stale lock file (server.lock) is present from a previous crash or ungraceful shutdown.

Fix:

# Force clear the stale lock and restart:
nakshastramcp start --force

Or stop the existing instance first:

nakshastramcp stop
nakshastramcp start

7. Windows Long Path Issues

Symptom: Indexing fails silently for files in deeply nested directories (paths > 260 characters).

Root Cause: Windows restricts path lengths to 260 characters by default. NakshAstraMCP’s doctor command checks for this under the Windows Long Paths check.

Fix: Enable long path support via PowerShell (requires Administrator):

# Enable Windows Long Paths
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -Type DWord

Or via Group Policy Editor: Computer Configuration → Administrative Templates → System → Filesystem → Enable Win32 long paths.

8. FlashRank Model Download Fails

Symptom: nakshastramcp doctor shows FAIL on the FlashRank Model Cache check. Reranking produces errors or is silently skipped.

Root Cause: The ms-marco-TinyBERT-L-2-v2 model couldn’t be downloaded (network restriction, proxy, or corporate firewall).

Fix:

  1. Download the model on a machine with open internet access and copy the cache directory.
  2. Or, if your corporate environment blocks the model hub, set the environment variable to use a local model path: 
    $env:FLASHRANK_CACHE_DIR = "C:\path\to\local\models"
  3. Rerun nakshastramcp doctor to confirm the model cache check passes.

📁 Log Locations & Streaming

Stream live logs directly to your terminal:

# Stream last 50 lines:
nakshastramcp logs

# Follow (tail -f mode):
nakshastramcp logs --follow

# Show last 100 lines:
nakshastramcp logs --lines 100

Rotating log files are stored locally in your system data directory:

Platform Log Directory
Windows %LOCALAPPDATA%\nakshastramcp\logs\
macOS ~/Library/Application Support/nakshastramcp/logs/
Linux ~/.local/share/nakshastramcp/logs/

[!NOTE] For absolute privacy, NakshAstraMCP never records source code content, variable values, or secret values in logs. Only file paths, timing metrics, and server state are tracked.

💬 Getting Further Help

If you’ve followed this guide and the issue persists:

  1. Run nakshastramcp doctor and collect the full output.
  2. Stream nakshastramcp logs --lines 100 and note any ERROR or WARNING lines.
  3. Visit GitHub Discussions — post your OS, version (nakshastramcp --version), and the relevant log lines.
  4. For bugs: Open a GitHub Issue using the bug report template.

🏠 Home · 🚀 Setup Guide · 📖 User Guide · 💬 Discussions