gRPC "received message larger than max" in CI

By Kaveh Alemi·Latchkey

gRPC caps received message size at 4 MB (4194304 bytes) by default. A larger response or request is rejected with RESOURCE_EXHAUSTED and "received message larger than max", failing the call until the limit is raised or the payload is reduced.

What this error means

A call fails with "8 RESOURCE_EXHAUSTED: Received message larger than max (5242880 vs. 4194304)" when returning a large list or blob in CI.

Error: 8 RESOURCE_EXHAUSTED: Received message larger than max (5242880 vs. 4194304)
    at Object.callErrorFromStatus (.../call.js)

Common causes

A response over the 4 MB default limit

A handler returns a large repeated field or embedded payload that exceeds the receiving side's default max message size.

No raised limit configured for known-large messages

The channel/server still uses the 4 MB default even though the API legitimately returns bigger messages.

How to fix it

Raise the max message size where appropriate

1. Identify whether the client receive, server receive, or server send limit applies.
2. Set grpc.max_receive_message_length (and send length) on that side.
3. Re-run the call with the larger limit configured.

const client = new UserService(addr, creds, {
  'grpc.max_receive_message_length': 16 * 1024 * 1024,
});

Stream or paginate large payloads

Prefer server streaming or pagination over single huge messages so no message approaches the limit.

rpc ListUsers (ListUsersRequest) returns (stream User);

How to prevent it

• Raise message-size limits explicitly for APIs that return large data.
• Stream or paginate instead of returning oversized single messages.
• Set the limit on both client and server sides as needed.

Frequently asked questions

Related guides

References

• GitHub Actions documentation