{"record":{"id":"83ea36f6c7fcb163","repo":"eyaltoledano/claude-task-master","slug":"sampling-error","errorCode":"SAMPLING_ERROR","errorMessage":"${message}","messagePattern":"\\$\\{message\\}","errorType":"error_code","errorClass":"MCPSamplingError","httpStatus":null,"severity":"warning","filePath":"mcp-server/src/custom-sdk/errors.js","lineNumber":66,"sourceCode":"\tif (error instanceof MCPError) {\n\t\treturn error;\n\t}\n\n\tconst message = error.message || 'Unknown MCP error';\n\tconst originalError = error;\n\n\t// Map common error patterns\n\tif (message.includes('session') || message.includes('connection')) {\n\t\treturn new MCPSessionError(message, {\n\t\t\tcause: originalError,\n\t\t\tcode: 'SESSION_ERROR'\n\t\t});\n\t}\n\n\tif (message.includes('sampling') || message.includes('timeout')) {\n\t\treturn new MCPSamplingError(message, {\n\t\t\tcause: originalError,\n\t\t\tcode: 'SAMPLING_ERROR'\n\t\t});\n\t}\n\n\tif (message.includes('capabilities') || message.includes('not supported')) {\n\t\treturn new MCPSessionError(message, {\n\t\t\tcause: originalError,\n\t\t\tcode: 'CAPABILITY_ERROR'\n\t\t});\n\t}\n\n\t// Default to generic MCP error\n\treturn new MCPError(message, {\n\t\tcause: originalError,\n\t\tcode: 'UNKNOWN_ERROR'\n\t});\n}\n\n/**","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/eyaltoledano/claude-task-master/blob/c0c98d367c55296bfe69e65680625b6db437af02/mcp-server/src/custom-sdk/errors.js#L48-L84","documentation":"mapMCPError re-wraps errors whose message contains 'sampling' or 'timeout' as MCPSamplingError with code SAMPLING_ERROR. Unlike session errors, isRetryableError returns true for SAMPLING_ERROR, so the library considers these retryable.","triggerScenarios":"A sampling request (createMessage) through the MCP client fails or exceeds its timeout — the underlying SDK throws with 'sampling' or 'timeout' in the message and mapMCPError (called by doGenerate/doGenerateObject/doStream) classifies it.","commonSituations":"Client capability sampling not approved/slow LLM backend; network latency causing timeouts; MCP server under load; very large prompts making sampling slow.","solutions":["Retry the request — SAMPLING_ERROR is marked retryable; add backoff","Increase the sampling/timeout configuration if requests are legitimately long","Verify the connected LLM backend behind MCP sampling is healthy","Check network stability between client and MCP server"],"exampleFix":"// before\nconst res = await doGenerate(prompt); // SAMPLING_ERROR on slow backend\n// after\nconst res = await retryWithBackoff(() => doGenerate(prompt), {\n  retryIf: (e) => e instanceof MCPSamplingError && isRetryableError(e)\n});","handlingStrategy":"retry","validationCode":"function samplingSupported(client) {\n  return Boolean(client.getServerCapabilities?.()?.sampling);\n}","typeGuard":"function isMCPSamplingError(e: unknown): e is MCPSamplingError {\n  return e instanceof MCPSamplingError || (typeof e === 'object' && e !== null && (e as any).code === 'SAMPLING_ERROR');\n}","tryCatchPattern":"try {\n  return await doGenerate(prompt);\n} catch (e) {\n  if (isMCPSamplingError(e) && isRetryableError(e)) {\n    await sleep(backoff(attempt));\n    return doGenerate(prompt);\n  }\n  throw e;\n}","preventionTips":["Retry with exponential backoff — the library marks SAMPLING_ERROR retryable","Set generous sampling timeouts for large prompts","Ensure the LLM backend behind MCP sampling is reachable and healthy"],"tags":["mcp","timeout","sampling","retryable"],"backgroundTag":"request-timeout","analyzedSha":"c0c98d367c55296bfe69e65680625b6db437af02","analyzedAt":"2026-08-29T02:56:26.071Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}