Docker "failed to solve: ResourceExhausted: grpc message exceeds max" in CI

By Daniel Zoghalchali·Latchkey

BuildKit talks to the daemon over gRPC, and gRPC caps the size of a single message. A build that pushes one oversized payload through that channel - a giant build context, a multi-gigabyte file in a single layer, or a bloated cache manifest - trips the ResourceExhausted limit and the solve fails.

What this error means

A docker buildx build aborts with failed to solve: ResourceExhausted: grpc: received message larger than max. It usually appears while transferring context or exporting a layer, not at a specific Dockerfile instruction.

ERROR: failed to solve: ResourceExhausted: grpc: received message larger than max (16777216 vs. 4194304)

Common causes

A single oversized file in one layer

A multi-hundred-megabyte artifact copied in one COPY/ADD can produce a single gRPC message that overruns the default limit.

A bloated build context sent in one shot

When .dockerignore is missing, the entire working tree (node_modules, build output, .git) is streamed and can overrun the message cap.

A large inline cache or metadata blob

An --cache-to type=inline or registry cache manifest that has grown very large can exceed the gRPC message size when imported or exported.

How to fix it

Shrink the build context with .dockerignore

1. Add the heavy directories to .dockerignore so they are never streamed.
2. Re-run the build and confirm the context size shrinks.

# .dockerignore
node_modules
dist
.git
*.tar
*.iso

Split the oversized COPY into smaller layers

1. Break one large COPY of many big files into several COPY instructions.
2. Fetch very large artifacts at runtime instead of baking them into a layer.

# instead of one giant COPY:
COPY ./assets/small ./assets/small
COPY ./assets/media ./assets/media
# or download at runtime:
RUN curl -fsSL https://artifacts.example.com/big.tar -o /tmp/big.tar

Raise the BuildKit gRPC message limit

1. If the payload is legitimately large, raise the limit in the buildkitd config used by your builder.
2. Re-create the buildx builder so it picks up the config.

# buildkitd.toml
[grpc]
  # bytes; default is 4 MiB
  maxRecvMsgSize = 67108864
  maxSendMsgSize = 67108864

How to prevent it

• Keep a tight .dockerignore so only intended files are sent.
• Avoid baking very large artifacts into a single layer.
• Raise the gRPC limit only when the payload is genuinely large.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation