# 内部错误：gRPC 标头大小超过 8192 字节的最大限制

- **ID:** `grpc/header-too-large`
- **领域:** grpc
- **类别:** protocol_error
- **错误码:** `EHDRSZ`
- **验证级别:** ai_generated
- **修复率:** 80%

## 根因

单个 RPC 调用中发送的 gRPC 元数据（标头）超过了 gRPC 框架强制执行的默认 8KB 限制。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| gRPC v1.61.0 | active | — | — |
| gRPC v1.58.0 | active | — | — |
| gRPC v1.55.0 | active | — | — |
| C++ gRPC v1.50.0 | active | — | — |

## 解决方案

1. ```
   在客户端和服务器上通过通道选项增加最大标头大小：Python 中使用 `grpc.max_metadata_size=16384`，C++ 中使用 `GRPC_ARG_MAX_METADATA_SIZE`。
   ```
2. ```
   通过将大型元数据拆分到多个 RPC 或使用单独的侧通道传输大型数据来减少元数据大小。
   ```

## 无效尝试

- **Increasing server-side max header size only** — The limit is enforced on both client and server; both sides must agree. (70% 失败率)
- **Compressing metadata using gRPC compression** — Metadata is not compressed by gRPC compression; only message payload is. (95% 失败率)
- **Sending metadata in the message body instead** — Metadata is designed for headers; moving it to body breaks protocol semantics. (80% 失败率)