Troubleshooting Guide

Common issues and solutions for the Darbot Deepmind MCP Server. Find quick fixes for installation, configuration, and runtime problems.

Quick Diagnostics

1. Server Not Starting

Symptom

The server fails to start or immediately exits without error messages.

Possible Causes & Solutions

Node.js Version Issue

# Check Node.js version
node --version

# Should be 18.0.0 or higher
# If not, install/update Node.js from nodejs.org

Port Already in Use

# Windows
netstat -an | findstr 3000

# macOS/Linux
lsof -i :3000

# If port is in use, kill the process or change MCP_PORT

Missing Dependencies

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Build Artifacts Missing

# Rebuild the project
npm run clean
npm run build

2. Tool Not Discovered

Symptom

Claude Desktop or VS Code shows "0 tools discovered" or the darbot_deepmind tool is not available.

Solutions

Verify Configuration File

Check JSON syntax and file paths:

# macOS
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
type %APPDATA%\Claude\claude_desktop_config.json

# Linux
cat ~/.config/Claude/claude_desktop_config.json

Restart MCP Client

• Claude Desktop: Completely quit and restart the application
• VS Code: Reload window (Ctrl+R or Cmd+R)

Verify Server Process

# Windows
tasklist | findstr node

# macOS/Linux
ps aux | grep darbot

Check MCP Protocol Version

Ensure your MCP client supports protocol version 0.5.0 or compatible.

3. Thought Logging Issues

Too Much Console Output

# Disable thought logging
export DISABLE_THOUGHT_LOGGING=true

# Windows PowerShell
$env:DISABLE_THOUGHT_LOGGING="true"

No Console Output at All

# Enable thought logging
export DISABLE_THOUGHT_LOGGING=false
export LOG_LEVEL=debug

# Windows PowerShell
$env:DISABLE_THOUGHT_LOGGING="false"
$env:LOG_LEVEL="debug"

Garbled or Broken Formatting

• Check terminal supports UTF-8 encoding
• Use a modern terminal (Windows Terminal, iTerm2, etc.)
• Verify Chalk color support with supports-color

4. Docker Container Issues

Container Exits Immediately

# Check Docker daemon
docker info

# View container logs
docker logs <container-id>

# Run in interactive mode for debugging
docker run -it --rm mcp/darbot-deepmind

Build Failures

# Clean build
docker system prune -a
docker build --no-cache -t mcp/darbot-deepmind .

Memory Limits

# Increase Docker memory
docker run --rm -i --memory=2g mcp/darbot-deepmind

5. NPX Installation Failures

NPX Command Hangs

# Clear npm cache
npm cache clean --force

# Use explicit registry
npx --registry https://registry.npmjs.org/ -y @darbotlabs/darbot-deepmind-mcp

Network/Proxy Issues

# Configure npm proxy
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# Or use local installation instead
npm install -g @darbotlabs/darbot-deepmind-mcp

Version Mismatch

# Check npm version (need 7+)
npm --version

# Update npm
npm install -g npm@latest

6. Memory or Performance Issues

Server Becomes Slow

For very long reasoning chains (100+ thoughts):

# Increase Node.js memory
node --max-old-space-size=4096 dist/index.js

Memory Leaks

• Break very long reasoning into smaller sessions
• Restart server periodically for long-running instances
• Monitor memory with htop or Task Manager

Performance Optimization

• Disable logging: DISABLE_THOUGHT_LOGGING=true
• Set log level to warn: LOG_LEVEL=warn
• Use production mode: NODE_ENV=production

7. Configuration Not Loading

Validate JSON Syntax

# Use online JSON validator or
cat config.json | python -m json.tool

Environment Variables Not Working

Ensure environment variables are defined in the env section of your MCP configuration:

{
  "mcpServers": {
    "darbot-deepmind": {
      "command": "npx",
      "args": ["-y", "@darbotlabs/darbot-deepmind-mcp"],
      "env": {
        "DISABLE_THOUGHT_LOGGING": "true"
      }
    }
  }
}

File Path Issues (Windows)

// Wrong (single backslash)
"C:\Users\Name\path"

// Correct (forward slash)
"C:/Users/Name/path"

// Also correct (escaped backslash)
"C:\\Users\\Name\\path"

8. TypeScript Compilation Errors

Type Errors

# Check TypeScript version
npx tsc --version

# Clean build
rm -rf dist
npm run build

Module Not Found

# Reinstall dependencies
rm -rf node_modules
npm install

# Check tsconfig.json paths

Build Cache Issues

# Clear TypeScript build cache
npm run clean
npm run build

9. Permission Issues (Linux/macOS)

Permission Denied Errors

# Make scripts executable
chmod +x dist/*.js

# Fix file ownership
sudo chown -R $USER:$USER /path/to/darbot-deepmind-mcp

Global Installation Issues

# Use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

# Or fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Debug Mode

Enable Full Debugging

# Linux/macOS
export LOG_LEVEL=debug
export DISABLE_THOUGHT_LOGGING=false
npm start

# Windows PowerShell
$env:LOG_LEVEL="debug"
$env:DISABLE_THOUGHT_LOGGING="false"
npm start

Collecting Debug Information

When reporting issues, include:

• Operating system and version
• Node.js version (node --version)
• npm version (npm --version)
• Package version (npm list @darbotlabs/darbot-deepmind-mcp)
• Complete error messages
• Configuration files (redacted if necessary)
• Steps to reproduce

Common Validation Errors

Error: thought must be non-empty

Cause: Empty or missing thought parameter

Fix: Provide a meaningful thought description

Error: revisesThought must be less than thoughtNumber

Cause: Trying to revise a future or current thought

Fix: Only revise past thoughts (revisesThought < thoughtNumber)

Error: revisesThought required when isRevision is true

Cause: Set isRevision without specifying which thought

Fix: Include the revisesThought parameter

Error: branchFromThought required when branchId is set

Cause: Provided branchId without branching point

Fix: Specify branchFromThought parameter

Getting Help

Check Existing Issues

Search the GitHub Issues for similar problems.

Create a Minimal Reproduction

Isolate the issue to the smallest possible test case that demonstrates the problem.

File a Bug Report

If you can't find a solution, open a new issue with:

• Clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Environment details
• Debug logs (with sensitive info redacted)

Prevention Tips

Best Practices

• Keep Node.js and npm updated
• Use version pinning for production deployments
• Test configuration changes in development first
• Enable debug logging during initial setup
• Monitor memory usage for long-running instances
• Regularly check for package updates
• Keep Docker images up to date

Health Checks

# Verify installation
npm list @darbotlabs/darbot-deepmind-mcp

# Check for updates
npm outdated @darbotlabs/darbot-deepmind-mcp

# Test server start
timeout 10s npm start || echo "Server started successfully"

Next Steps