# Unknown methods return -32601 Method not found

- **Pattern:** `ab-001842` (`mcp-server.error-resilience.method-not-found`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-001842
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-001842)

## Why it matters

When a client sends a request for an unrecognized method, the JSON-RPC 2.0 spec requires a `-32601 Method not found` error response. A custom server without a fallback case silently drops the request — the client hangs indefinitely waiting for a response that never arrives. This is CWE-703: the unhandled case is a real input condition in production (a newer client calling a method the server hasn't implemented yet). Returning the wrong error code, like `-32603 Internal error`, misleads the client into treating a known gap as an unexpected server failure.

## Severity rationale

High because missing a default error case causes client hangs on any unrecognized method call, which in agentic workflows can freeze an entire session without a visible error.

## Remediation

Add a default case to every message router that returns `-32601`. The MCP SDK handles this automatically — only custom implementations need explicit treatment.

```ts
// src/transport/router.ts
function handleRequest(request: JsonRpcRequest) {
  switch (request.method) {
    case 'initialize': return handleInitialize(request)
    case 'tools/list':  return handleToolsList(request)
    case 'tools/call':  return handleToolsCall(request)
    default:
      return {
        jsonrpc: '2.0',
        id: request.id,
        error: { code: -32601, message: `Method not found: ${request.method}` }
      }
  }
}
```

## Detection

- **ID:** `method-not-found`
- **Severity:** `high`
- **What to look for:** Enumerate the server's handling of unknown method names. Count whether unrecognized methods return -32601 MethodNotFound error. Check how the server handles requests for methods it does not implement. When a client sends a request with an unknown `method` field, the server should respond with JSON-RPC error code -32601 (Method not found). For SDK-based servers, this is handled automatically. For custom implementations, check for a default/fallback case in the message router.
- **Pass criteria:** Unknown method requests receive a -32601 error response with a descriptive message. The server does not crash, hang, or silently ignore unknown methods. 100% of unknown method calls must return a -32601 error code.
- **Fail criteria:** Unknown methods cause a crash, are silently ignored (no response), or return an incorrect error code.
- **Skip (N/A) when:** All checks skip when no MCP server is detected.

- **Cross-reference:** For structured error codes, see `structured-errors`.
- **Detail on fail:** `"Custom message router has no default case — unknown methods are silently ignored and no response is sent. The client will hang waiting for a response"` or `"Unknown methods return error code -32603 (Internal Error) instead of -32601 (Method not found)"`
- **Remediation:** Always have a fallback for unknown methods:

  ```ts
  // The MCP SDK handles MethodNotFound automatically in src/index.ts
  // Verify: calling a non-existent method returns { error: { code: -32601, message: "Method not found" } }
  ```

  ```ts
  function handleRequest(request: JsonRpcRequest) {
    switch (request.method) {
      case 'initialize': return handleInitialize(request)
      case 'tools/list': return handleToolsList(request)
      case 'tools/call': return handleToolsCall(request)
      // ... other methods
      default:
        return {
          jsonrpc: '2.0',
          id: request.id,
          error: { code: -32601, message: `Method not found: ${request.method}` }
        }
    }
  }
  ```

## External references

- cwe CWE-703
- external jsonrpc-2.0-error-codes — https://www.jsonrpc.org/specification#error_object

Taxons: error-resilience, inference-contract

HTML version: https://auditbuffet.com/patterns/ab-001842