Code Executor Troubleshooting Guide

This skill helps you diagnose and fix common issues when using Code Executor MCP.

Quick Diagnostic Workflow

When

execute_code

Step 1: Check Server Availability

Tool: list_available_servers

Look for your server's status:

• "ready" → Server wrapper exists, proceed to Step 2
• "disabled" → Enable in mcp.json (

  "enabled": true

  )
• "no-wrapper" → Run

  pnpm run gen

  to generate wrappers

Step 2: Verify Tool Exists

Tool: list_server_tools
Args: { "server": "your-server-name" }

Important: Copy the exact import statement from the output! Don't guess.

Step 3: Test Server Connection

Tool: test_server_connection
Args: { "server": "your-server-name" }

If this fails, the MCP server is not responding. Check:

• Is the server command installed?
• Are there dependency issues?
• Check stderr with

  get_server_stderr

Step 4: Check Server Health

Tool: check_server_health
Args: { "server": "your-server-name" }

Shows detailed diagnostics including:

• Command path and arguments
• Timeout settings
• Connection status
• Error suggestions

Step 5: Get Server Stderr

Tool: get_server_stderr
Args: { "server": "your-server-name" }

Shows any error output from the server process startup.

Common Error Patterns

Import Errors

Cannot find module '../servers/X'

/index.js

/index.js

Cannot find module '../servers/X/index'

.js

.js

ERR_MODULE_NOT_FOUND

list_server_tools

X is not exported from module

list_server_tools

does not provide an export named

list_server_tools

Correct Import Examples:

// ✅ Correct - full path with .js
import { resolveLibraryId } from '../servers/context7/index.js';

// ✅ Correct - direct file import
import * as tool from '../servers/context7/resolve-library-id.js';

// ❌ Wrong - missing /index.js
import { resolveLibraryId } from '../servers/context7';

// ❌ Wrong - missing .js extension
import { resolveLibraryId } from '../servers/context7/index';

Function Call Errors

X is not a function

tool({ args })

tool.call({ args })

call is not a function

list_server_tools

Correct Call Patterns:

// ✅ Both patterns work
const result = await resolveLibraryId({ libraryName: "react" });
const result = await resolveLibraryId.call({ libraryName: "react" });

// ❌ Wrong - double call
const result = await resolveLibraryId.call.call({ ... });

Execution Hangs

debug: true

debug: true

test_server_connection

Debugging Hanging Execution:

execute_code({
  code: "...",
  debug: true  // ← Shows connection/call progress
})

Debug output progression:

1. [server] Connecting...

   - Starting connection to MCP server

2. [server] Calling toolName...

   - Connection succeeded, making tool call

3. [server] Call completed.

   - Tool returned successfully

If it hangs at step 1: Server is not starting properly If it hangs at step 2: Tool execution is slow or stuck

Server Connection Errors

Server "X" not found in config

list_available_servers

Server "X" is disabled

"enabled": true

Command not found

Connection timed out

timeout

Parameter Errors

Required parameter missing

get_tool_schema

Invalid enum value

get_tool_schema

Type error

Timeout Configuration

If operations are too slow, configure timeouts in

mcp.json

{
  "servers": {
    "your-server": {
      "command": "npx",
      "args": ["your-mcp-server"],
      "timeout": 120000,      // Connection timeout (ms)
      "callTimeout": 60000,   // Tool call timeout (ms)
      "retries": 3,           // Connection retry count
      "retryDelay": 1000      // Delay between retries (ms)
    }
  }
}

Or use per-call timeout:

const result = await tool.call({ args }, { timeout: 60000 });

Server-Specific Issues

Context7 Server

• Requires valid library names
• Use

  resolveLibraryId

  first to get the correct ID
• Then use that ID with

  getLibraryDocs

Sequential Thinking Server

• Requires specific stage values
• Use

  get_tool_schema

  to see valid stage enum values
• Must call

  clear-history

  before starting new session

Recovery Steps

If you've tried everything and it still doesn't work:

1. Regenerate wrappers:

   pnpm run gen

2. Clear cached config: Restart the MCP server
3. Check server logs:

   get_server_stderr

4. Test manually: Run the server command directly in terminal
5. Check dependencies: Ensure all npm packages are installed

Quick Reference Card

┌─────────────────────────────────────────────────────┐
│  CODE EXECUTOR TROUBLESHOOTING QUICK REFERENCE     │
├─────────────────────────────────────────────────────┤
│  1. list_available_servers    → See ready servers   │
│  2. list_server_tools         → Get import paths    │
│  3. execute_code {debug:true} → See where it hangs  │
│  4. test_server_connection    → Test connectivity   │
│  5. check_server_health       → Detailed diagnostics│
│  6. get_server_stderr         → Error output        │
├─────────────────────────────────────────────────────┤
│  IMPORT PATTERN:                                    │
│  import { X } from '../servers/NAME/index.js';      │
│                          ↑            ↑             │
│                     server name    MUST have .js    │
├─────────────────────────────────────────────────────┤
│  CALL PATTERN:                                      │
│  await tool({ param: "value" });                    │
│  await tool.call({ param: "value" });               │
└─────────────────────────────────────────────────────┘