eyaltoledano/claude-task-master · error · MCPSessionError

SESSION_ERROR

SESSION_ERROR

Error message

${message}

What it means

mapMCPError classifies arbitrary thrown errors by substring-matching their message. If the message contains 'session' or 'connection', it is re-wrapped as MCPSessionError with code SESSION_ERROR, preserving the original as cause. isRetryableError treats SESSION_ERROR as non-retryable.

Source

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

/**
 * Map MCP errors to AI SDK compatible error types
 * @param {Error} error - Original error
 * @returns {Error} Mapped error
 */
export function mapMCPError(error) {
	// If already an MCP error, return as-is
	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

View on GitHub (pinned to c0c98d367c)

Solutions

1. Reconnect to the MCP server and create a fresh session, then retry the request
2. Check that the MCP server process is running and the transport config (stdio command / URL) is correct
3. Inspect error.cause for the underlying transport failure
4. Do not blind-retry: SESSION_ERROR is classified as non-retryable without a new session

Example fix

// before
const res = await doGenerate(prompt); // throws after server restart
// after
try {
  const res = await doGenerate(prompt);
} catch (e) {
  if (e instanceof MCPSessionError) { await reconnect(); return doGenerate(prompt); }
  throw e;
}

function checkServerConnection(client) {
  return client.isConnected?.() ?? true; // verify transport before expensive calls
}

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

try {
  await doGenerate(prompt);
} catch (e) {
  if (isMCPSessionError(e)) {
    await reconnectAndCreateSession();
    return doGenerate(prompt); // retry only after fresh session
  }
  throw e;
}

When it happens

Trigger: doGenerate/doGenerateObject/doStream call mapMCPError on any error whose message mentions the MCP session or connection — e.g. server disconnected mid-request, session expired, transport closed.

Common situations: MCP server process crashed or was restarted; stdio/HTTP transport dropped; long-lived session idle-timed out; load balancer cut a persistent connection.

Related errors

• MCP Provider requires active MCP session
• MCP session must have client sampling capabilities
• projectRoot is required in args to resolve project paths
• MCP provider requires session object
• The MCP model function cannot be called with the new keyword

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