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

# PrefillErrorHandler

`PrefillErrorHandler` 是一個 **error processor**，用於處理助理回應預填錯誤。如果對話以助理訊息結束，而模型因將其解讀為預填助理回應而拒絕請求，就會出現此錯誤。

偵測到錯誤時，Processor 會傳送一個隱藏的 `system-reminder` signal，以 `continue` 作為其內容，並發出重試指示。該提醒會以 signal metadata 的形式持久保存，因此可用於重試重建及原始記錄，而面向標準 UI 的訊息轉換則會將其隱藏。

如要 Mastra 從助理預填拒絕中復原（例如 Anthropic 的「assistant message prefill」以及 Qwen/llama.cpp 的「assistant response prefill is incompatible with `enable_thinking`」錯誤），請將此 Processor 加入 `errorProcessors`。

## 運作方式

1. LLM API 呼叫因已知的助理預填拒絕訊息而失敗
2. `PrefillErrorHandler` 檢查這是否為首次重試
3. 它傳送一個隱藏的 `system-reminder` signal，以 `continue` 作為其內容
4. 它傳回 `{ retry: true }`，指示應使用修改後的訊息重試 LLM 呼叫

Processor 現在會直接因應 API 拒絕，而不再重新檢查對話目前是否以助理訊息結束。即使末端訊息的形式已在上游完成轉換，Provider 仍可能因預填語義而拒絕請求；此做法可令 Processor 妥善處理這些情況。

## 使用範例

對於任何應在助理預填失敗後重試的 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()],
})
```

如需自訂復原行為，請提供具備 `processAPIError` 方法的自訂 error processor：

```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 並發出重試指示，處理已知的助理預填錯誤。只會在首次重試時觸發。

## 相關內容

- [Processor 介面](https://mastra.zisheng.pro/zh-HK/reference/processors/processor-interface)
- [Guardrails](https://mastra.zisheng.pro/zh-HK/docs/agents/guardrails)