@mastra/core/dist/docs/references/reference-processors-prefill-error-handler.md

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

# PrefillErrorHandler

The `PrefillErrorHandler` is an **error processor** that handles assistant-response prefill errors. This error occurs when a conversation ends with an assistant message and the model rejects the request because it interprets it as prefilling the assistant response.

When the error is detected, the processor sends a hidden `system-reminder` signal with `continue` as its contents and signals a retry. The reminder is persisted as signal metadata, which keeps it available for retry reconstruction and raw history while standard UI-facing message conversions hide it.

Add this processor to `errorProcessors` when you want Mastra to recover from assistant prefill rejections (for example Anthropic's "assistant message prefill" and Qwen/llama.cpp's "assistant response prefill is incompatible with `enable_thinking`" errors).

## How it works

1. The LLM API call fails with a known assistant-prefill rejection message
2. `PrefillErrorHandler` checks that this is the first retry attempt
3. It sends a hidden `system-reminder` signal with `continue` as its contents
4. It returns `{ retry: true }` to signal the LLM call should be retried with the modified messages

The processor now reacts to the API rejection itself instead of re-checking whether the conversation currently ends with an assistant message. This makes it resilient to cases where the provider rejects the request for prefill semantics even if the trailing message shape has already been transformed upstream.

## Usage example

Add `PrefillErrorHandler` to `errorProcessors` for any agent that should retry assistant-prefill failures:

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

export const agent = new Agent({
  name: 'my-agent',
  instructions: 'You are a helpful assistant.',
  model: 'anthropic/claude-opus-4-6',
  errorProcessors: [new PrefillErrorHandler()],
})
```

If you want custom recovery behavior, provide your own error processor with a `processAPIError` method:

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

const customErrorHandler: Processor = {
  id: 'custom-prefill-error-handler',
  processAPIError({ error, messageList, retryCount }) {
    // Your custom logic here
  },
}

export const agent = new Agent({
  name: 'my-agent',
  instructions: 'You are a helpful assistant.',
  model: 'anthropic/claude-opus-4-6',
  errorProcessors: [customErrorHandler],
})
```

## Constructor parameters

The `PrefillErrorHandler` takes no constructor parameters.

## Properties

**id** (`'prefill-error-handler'`): Processor identifier.

**name** (`'Prefill Error Handler'`): Processor display name.

**processAPIError** (`(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void`): Handles known assistant-prefill errors by sending a hidden system reminder signal and signaling retry. Only triggers on the first retry attempt.

## Related

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