> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# PrefillErrorHandler

`PrefillErrorHandler` 是一个**错误 Processor**，用于处理 assistant 响应预填充错误。当对话以 assistant 消息结尾，并且模型因将其解读为预填充 assistant 响应而拒绝请求时，就会出现此错误。

检测到错误后，Processor 会发送一个隐藏的 `system-reminder` signal，其内容为 `continue`，并发出重试 signal。该提醒会作为 signal metadata 持久化，因此在重试重建和原始历史记录中仍然可用，而面向标准 UI 的消息转换会将其隐藏。

如果希望 Mastra 从 assistant 预填充拒绝中恢复，请将此 Processor 添加到 `errorProcessors`（例如 Anthropic 的 "assistant message prefill"，以及 Qwen/llama.cpp 的 "assistant response prefill is incompatible with `enable_thinking`" 错误）。

## 工作原理

1. LLM API 调用失败，并返回已知的 assistant 预填充拒绝消息
2. `PrefillErrorHandler` 检查这是否为首次重试
3. 它发送一个隐藏的 `system-reminder` signal，其内容为 `continue`
4. 它返回 `{ retry: true }`，表示应使用修改后的消息重试 LLM 调用

Processor 现在直接响应 API 拒绝，而不再重新检查对话当前是否以 assistant 消息结尾。因此，即使末尾消息的结构已在上游完成转换，当 Provider 仍因预填充语义拒绝请求时，它也能可靠处理。

## 用法示例

对于任何需要在 assistant 预填充失败时进行重试的 Agent，请将 `PrefillErrorHandler` 添加到 `errorProcessors`：

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

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

如需自定义恢复行为，请提供自己的错误 Processor，并实现 `processAPIError` 方法：

```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({
  id: 'my-agent',
  name: 'my-agent',
  instructions: 'You are a helpful assistant.',
  model: 'anthropic/claude-opus-4-7',
  errorProcessors: [customErrorHandler],
})
```

## 构造函数参数

`PrefillErrorHandler` 不接受任何构造函数参数。

## 属性

**id** (`'prefill-error-handler'`): Processor 标识符。

**name** (`'Prefill Error Handler'`): Processor 显示名称。

**processAPIError** (`(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void`): 通过发送隐藏的 system reminder signal 并发出重试 signal 来处理已知的 assistant 预填充错误。仅在首次重试时触发。

## 相关内容

- [Processor 接口](https://mastra.zisheng.pro/reference/processors/processor-interface)
- [Guardrails](https://mastra.zisheng.pro/docs/agents/guardrails)