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:

src/mastra/agents/my-agent.ts

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:

src/mastra/agents/custom-error-handling.ts

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
• Guardrails