# INTERNAL: grpc: received metadata size exceeds limit

- **ID:** `grpc/metadata-too-large`
- **Domain:** grpc
- **Category:** resource_error
- **Verification:** ai_generated
- **Fix Rate:** 82%

## Root Cause

The gRPC metadata (headers/trailers) sent with an RPC exceeds the default size limit (usually 8 KB), often due to large authentication tokens or custom headers.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| gRPC C++ 1.55+ | active | — | — |
| gRPC Java 1.55+ | active | — | — |
| gRPC .NET 2.50+ | active | — | — |

## Workarounds

1. **Increase max metadata size on both client and server. In C++ server: builder.AddChannelArgument(GRPC_ARG_MAX_METADATA_SIZE, 16384); On client: grpc.InsecureChannelCredentials().SetMaxMetadataSize(16384)** (90% success)
   ```
   Increase max metadata size on both client and server. In C++ server: builder.AddChannelArgument(GRPC_ARG_MAX_METADATA_SIZE, 16384); On client: grpc.InsecureChannelCredentials().SetMaxMetadataSize(16384)
   ```
2. **Move large data (e.g., tokens) to the message body instead of metadata. In Go: send token as first field in protobuf message and extract on server side.** (85% success)
   ```
   Move large data (e.g., tokens) to the message body instead of metadata. In Go: send token as first field in protobuf message and extract on server side.
   ```

## Dead Ends

- **Increasing max metadata size on client only** — Server still enforces its own limit; the error may persist if server limit is not also increased. (45% fail)
- **Removing all custom headers** — May break authentication or routing logic that depends on headers. (30% fail)