eyaltoledano/claude-task-master · warning · MCPSamplingError

SAMPLING_ERROR

SAMPLING_ERROR

Error message

${message}

What it means

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.

Source

Thrown at mcp-server/src/custom-sdk/errors.js:66

	if (error instanceof MCPError) {
		return error;
	}

	const message = error.message || 'Unknown MCP error';
	const originalError = error;

	// Map common error patterns
	if (message.includes('session') || message.includes('connection')) {
		return new MCPSessionError(message, {
			cause: originalError,
			code: 'SESSION_ERROR'
		});
	}

	if (message.includes('sampling') || message.includes('timeout')) {
		return new MCPSamplingError(message, {
			cause: originalError,
			code: 'SAMPLING_ERROR'
		});
	}

	if (message.includes('capabilities') || message.includes('not supported')) {
		return new MCPSessionError(message, {
			cause: originalError,
			code: 'CAPABILITY_ERROR'
		});
	}

	// Default to generic MCP error
	return new MCPError(message, {
		cause: originalError,
		code: 'UNKNOWN_ERROR'
	});
}

/**

View on GitHub (pinned to c0c98d367c)

Solutions

1. Retry the request — SAMPLING_ERROR is marked retryable; add backoff
2. Increase the sampling/timeout configuration if requests are legitimately long
3. Verify the connected LLM backend behind MCP sampling is healthy
4. Check network stability between client and MCP server

Example fix

// before
const res = await doGenerate(prompt); // SAMPLING_ERROR on slow backend
// after
const res = await retryWithBackoff(() => doGenerate(prompt), {
  retryIf: (e) => e instanceof MCPSamplingError && isRetryableError(e)
});

function samplingSupported(client) {
  return Boolean(client.getServerCapabilities?.()?.sampling);
}

function isMCPSamplingError(e: unknown): e is MCPSamplingError {
  return e instanceof MCPSamplingError || (typeof e === 'object' && e !== null && (e as any).code === 'SAMPLING_ERROR');
}

try {
  return await doGenerate(prompt);
} catch (e) {
  if (isMCPSamplingError(e) && isRetryableError(e)) {
    await sleep(backoff(attempt));
    return doGenerate(prompt);
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: Client capability sampling not approved/slow LLM backend; network latency causing timeouts; MCP server under load; very large prompts making sampling slow.

Related errors

• MCP session must have client sampling capabilities
• MCP session must have client sampling capabilities
• TIMEOUT
• projectRoot is required in args to resolve project paths
• MCP provider requires session object

AI-assisted analysis of eyaltoledano/claude-task-master@c0c98d367c (2026-08-29). Data as JSON: /api/errors/83ea36f6c7fcb163. Report an issue: GitHub.