@mastra/core/dist/docs/references/reference-processors-stream-error-retry-processor.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# StreamErrorRetryProcessor

`StreamErrorRetryProcessor` is an **error processor** that retries transient errors emitted after an LLM stream starts. It includes built-in matching for OpenAI Responses stream errors and supports additional matchers for other provider-specific stream error shapes.

The processor isn't enabled by default in core. Add it to `errorProcessors` for agents that need stream-error retry handling.

## Usage example

Add `StreamErrorRetryProcessor` to `errorProcessors`:

```typescript
import { Agent } from '@mastra/core/agent'
import { StreamErrorRetryProcessor } from '@mastra/core/processors'

export const agent = new Agent({
  name: 'openai-agent',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-5',
  errorProcessors: [new StreamErrorRetryProcessor()],
})
```

## How it works

The processor checks the error and its cause chain for:

- Provider retry metadata: `isRetryable === true`
- Built-in OpenAI Responses stream error matching
- Matcher results: Any configured matcher that returns `true`

When the error is retryable, the processor returns `{ retry: true }`. It doesn't mutate messages.

## Default OpenAI Responses matcher

`isRetryableOpenAIResponsesStreamError` matches OpenAI Responses stream error chunks with `type: 'error'` or `type: 'response.failed'`. It retries known transient OpenAI error codes and, as a fallback, errors with explicit retry guidance such as `You can retry your request`.

`StreamErrorRetryProcessor` includes this matcher by default. You can also import it and reuse it in custom retry logic.

## Constructor parameters

**options** (`StreamErrorRetryProcessorOptions`): Configuration for retry handling.

## Properties

**id** (`'stream-error-retry-processor'`): Processor identifier.

**name** (`'Stream Error Retry Processor'`): Processor display name.

**processAPIError** (`(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void`): Retries stream errors up to the configured retry limit.

## Related

- [Processor interface](https://mastra.ai/reference/processors/processor-interface)
- [Processors](https://mastra.ai/docs/agents/processors)