eyaltoledano/claude-task-master · warning · MCPError

UNKNOWN_ERROR

UNKNOWN_ERROR

Error message

${message}

What it means

The fallback branch of mapMCPError: any error whose message matches none of the known patterns (session/connection, sampling/timeout, capabilities/not supported) is wrapped as a generic MCPError with code UNKNOWN_ERROR, keeping the original as cause.

Source

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

	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'
	});
}

/**
 * Check if error is retryable
 * @param {Error} error - Error to check
 * @returns {boolean} True if error might be retryable
 */
export function isRetryableError(error) {
	if (error instanceof MCPSamplingError && error.code === 'SAMPLING_ERROR') {
		return true;
	}

	if (error instanceof MCPSessionError && error.code === 'SESSION_ERROR') {
		// Session errors are generally not retryable
		return false;
	}

View on GitHub (pinned to c0c98d367c)

Solutions

1. Inspect error.cause and the message for the true root cause
2. Log the full error to extend mapMCPError's pattern list if it's a recurring class
3. Fix the underlying request/payload issue indicated by the cause
4. If recurring, file/patch the mapping so it's classified properly instead of UNKNOWN

Example fix

// before
catch (e) { console.log(e.code); // UNKNOWN_ERROR — dead end
// after
catch (e) { console.error(e.message, e.cause); /* diagnose real cause */ }

// Nothing to pre-validate: this is the catch-all branch. Ensure inputs/serialization are well-formed:
JSON.stringify(payload); // throws early on circular structures

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

try {
  await doGenerate(prompt);
} catch (e) {
  if (isUnknownMCPError(e)) {
    logger.error('Unclassified MCP error', { message: e.message, cause: e.cause });
  }
  throw e;
}

When it happens

Trigger: doGenerate/doGenerateObject/doStream surface an error with an unrecognized message — JSON-RPC internal errors, malformed responses, deserialization failures, or new error types the pattern matcher doesn't know.

Common situations: New/renamed upstream error messages breaking substring matching; server returning non-standard JSON-RPC errors; bugs in response payload handling.

Related errors

• 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
• MCP session must have client sampling capabilities
• Schema is required for object generation

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