Kodebase
Troubleshooting

Troubleshooting

Common issues and solutions for Kodebase setup and usage

This guide covers common issues you might encounter when setting up and using Kodebase, along with solutions and debugging tips.

Installation Issues

MCP Server Not Found

Symptoms:

  • AI assistant shows "Tool not available" or "Server not found"
  • No Kodebase tools appear in the tool list

Causes and Solutions:

  1. Config file in wrong location

    Check your MCP config file is in the correct location:

    ClientConfig Path
    Claude Code (macOS)~/.claude/claude_desktop_config.json
    Claude Code (Windows)%APPDATA%\Claude\claude_desktop_config.json
    Claude Code (Linux)~/.config/claude/claude_desktop_config.json
    Cursor (project).cursor/mcp.json
    Cursor (global)~/.cursor/mcp.json

  2. Invalid JSON syntax

    Validate your config file has valid JSON:

    # macOS/Linux
cat ~/.claude/claude_desktop_config.json | python -m json.tool

# Or use an online JSON validator

  3. Missing kodebase entry

    Ensure your config includes the kodebase server:

    {
  "mcpServers": {
    "kodebase": {
      "command": "npx",
      "args": ["kodebase@latest"],
      "env": {
        "KODEBASE_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

  4. Restart required

    After updating the config, restart your AI assistant (Claude Code or Cursor) completely.

Node.js Version Incompatibility

Symptoms:

  • Error: Unsupported engine
  • Error: SyntaxError: Unexpected token
  • Server fails to start

Solution:

Kodebase requires Node.js 22 or later. Check your version:

node --version

If you need to upgrade:

# Using nvm (recommended)
nvm install 22
nvm use 22

# Or download from nodejs.org

Permission Denied During npm Install

Symptoms:

  • Error: EACCES: permission denied
  • Error: npm ERR! code EACCES

Solutions:

  1. Don't use sudo with npm

    Instead, fix npm permissions:

    mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# Add to your shell profile (~/.bashrc or ~/.zshrc):
export PATH=~/.npm-global/bin:$PATH

  2. Use npx instead of global install

    The recommended approach avoids global installs:

    {
  "mcpServers": {
    "kodebase": {
      "command": "npx",
      "args": ["kodebase@latest"]
    }
  }
}

Environment Issues

KODEBASE_PROJECT_ROOT Not Set or Invalid

Symptoms:

  • Error: Configuration not found
  • Error: Cannot find .kodebase directory
  • Tools work but can't find artifacts

Solutions:

  1. Set the environment variable

    In your MCP config:

    {
  "mcpServers": {
    "kodebase": {
      "command": "npx",
      "args": ["kodebase@latest"],
      "env": {
        "KODEBASE_PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

  2. Use absolute paths

    The path must be absolute, not relative:

    // ✓ Correct
"KODEBASE_PROJECT_ROOT": "/Users/yourname/projects/my-app"

// ✗ Wrong
"KODEBASE_PROJECT_ROOT": "./my-app"
"KODEBASE_PROJECT_ROOT": "~/projects/my-app"

  3. Verify the path exists

    ls -la /path/to/your/project/.kodebase

.kodebase/artifacts Directory Not Found

Symptoms:

  • Error: Artifact not found
  • sherpa_get_status returns empty results
  • Scout can't generate artifacts

Solutions:

  1. Initialize Kodebase in your project

    cd /path/to/your/project
kb init

  2. Create the directory structure manually

    mkdir -p .kodebase/artifacts
mkdir -p .kodebase/config

  3. Check you're in the right directory

    Verify KODEBASE_PROJECT_ROOT points to a project with .kodebase/:

    ls -la $KODEBASE_PROJECT_ROOT/.kodebase/

MCP Connection Issues

Claude Code Doesn't Show Kodebase Tools After Config Update

Symptoms:

  • Updated config but tools don't appear
  • Old tool list showing

Solutions:

  1. Restart Claude Code completely

    • Quit Claude Code entirely (not just close window)
    • Wait a few seconds
    • Reopen Claude Code

  2. Verify config file location

    The config might be in a different location than expected. Check both:

    • ~/.claude/claude_desktop_config.json
    • Your project's .claude/mcp.json

  3. Ask the assistant to list tools

    After restart, ask: "What Kodebase tools do you have access to?"

    Expected tools:

    • scout_start_session
    • scout_submit_answers
    • scout_validate_spec
    • scout_generate_artifacts
    • sherpa_get_status
    • sherpa_get_context
    • sherpa_get_guidance
    • kodebase_get_config
    • kodebase_update_config

How to Check MCP Server Logs

For debugging connection issues:

  1. Run the server manually

    # Set the project root and run
KODEBASE_PROJECT_ROOT=/path/to/project npx kodebase@latest

    If there are startup errors, they'll appear in the terminal.

  2. Use MCP Inspector

    npx @modelcontextprotocol/inspector npx kodebase@latest

    This opens a web interface where you can:

    • See all registered tools
    • Test tool calls interactively
    • View request/response logs

  3. Check Claude Code logs

    On macOS, check:

    tail -f ~/Library/Logs/Claude/mcp*.log

How to Verify the Server Is Running Correctly

Quick verification steps:

  1. Test the server starts

    KODEBASE_PROJECT_ROOT=/path/to/project npx kodebase@latest
# Should start without errors
# Press Ctrl+C to stop

  2. Test tool availability

    Ask your AI assistant:

    What Kodebase tools do you have access to?

  3. Test a simple tool call

    Ask your AI assistant:

    Can you run kodebase_get_config to check the current configuration?

  4. Test artifact discovery

    Ask your AI assistant:

    What issues are ready to start? (use sherpa_get_status)

Common Runtime Errors

Session Not Found

Error: Session not found: scout-xxxxx-xxxxxx

Cause: The Scout session has expired or was never created.

Solution: Start a new session with scout_start_session.

Artifact Not Found

Error: Artifact not found: A.1.1

Causes:

  • The artifact ID doesn't exist
  • KODEBASE_PROJECT_ROOT points to wrong directory
  • Artifacts haven't been created yet

Solution: Check the artifact exists:

ls -la $KODEBASE_PROJECT_ROOT/.kodebase/artifacts/

Invalid Phase Transition

Error: Invalid phase transition from 'gathering' to 'approved'

Cause: Scout sessions must progress through phases in order.

Solution: Follow the phase sequence:

  1. gathering → refining
  2. refining → validating
  3. validating → approved

Dependencies Not Met

Error: Issue A.1.2 has unmet dependencies: A.1.1

Cause: Trying to start an issue that's blocked by incomplete dependencies.

Solution: Complete the blocking issues first, or use sherpa_get_status to find issues that are ready.

Getting Help

If you're still experiencing issues:

  1. Check the documentation

  2. Join the community

    • Discord - Get help from the community

  3. Report a bug

When reporting issues, please include:

  • Your operating system
  • Node.js version (node --version)
  • Kodebase version (npx kodebase@latest --version)
  • The full error message
  • Steps to reproduce the issue

MCP Tools

Complete reference for Kodebase MCP tools

Known Limitations

Alpha limitations and expectations for Kodebase testers

On this page

Installation IssuesMCP Server Not FoundNode.js Version IncompatibilityPermission Denied During npm InstallEnvironment IssuesKODEBASE_PROJECT_ROOT Not Set or Invalid.kodebase/artifacts Directory Not FoundMCP Connection IssuesClaude Code Doesn't Show Kodebase Tools After Config UpdateHow to Check MCP Server LogsHow to Verify the Server Is Running CorrectlyCommon Runtime ErrorsSession Not FoundArtifact Not FoundInvalid Phase TransitionDependencies Not MetGetting Help