# INTERNAL: grpc: header size exceeds max limit of 8192 bytes

- **ID:** `grpc/header-too-large`
- **Domain:** grpc
- **Category:** protocol_error
- **Error Code:** `EHDRSZ`
- **Verification:** ai_generated
- **Fix Rate:** 80%

## Root Cause

gRPC metadata (headers) sent in a single RPC call exceeds the default 8KB limit enforced by the gRPC framework.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| gRPC v1.61.0 | active | — | — |
| gRPC v1.58.0 | active | — | — |
| gRPC v1.55.0 | active | — | — |
| C++ gRPC v1.50.0 | active | — | — |

## Workarounds

1. **Increase the max header size on both client and server via channel option: `grpc.max_metadata_size=16384` in Python, or `GRPC_ARG_MAX_METADATA_SIZE` in C++.** (85% success)
   ```
   Increase the max header size on both client and server via channel option: `grpc.max_metadata_size=16384` in Python, or `GRPC_ARG_MAX_METADATA_SIZE` in C++.
   ```
2. **Reduce metadata size by splitting large metadata across multiple RPCs or using a separate side channel for large data.** (75% success)
   ```
   Reduce metadata size by splitting large metadata across multiple RPCs or using a separate side channel for large data.
   ```

## Dead Ends

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