What causes "grpc: received message larger than max (%d vs. %d)" in micro/go-micro?

Increase MaxMessageSize on the codec for both client and server (micro codec options).

grpc: received message larger than max

Error message

grpc: received message larger than max (%d vs. %d)

What it means

The gRPC codec enforces MaxMessageSize when decoding a length-prefixed frame: if the declared message length exceeds MaxMessageSize, decode aborts with this error before allocating the buffer. The two values printed are the received length and the configured max.

Solutions

Increase MaxMessageSize on the codec for both client and server (micro codec options).
Chunk large payloads into smaller messages.
Compress payloads before sending.
Confirm both sides agree on the same MaxMessageSize configuration.

Example fix

// before
c := grpc.NewCodec()
// after
c := grpc.NewCodec(codec.MaxMessageSize(1024 * 1024 * 16)) // 16MB

Defensive patterns

Strategy: validation

Validate before calling

// Enforce a client-side size limit before sending:
if len(payload) > maxAllowed {
	return fmt.Errorf("payload %d exceeds codec max %d; chunk or raise MaxMessageSize", len(payload), maxAllowed)
}

Try / catch

if err := client.Call(ctx, req, resp); err != nil {
	if strings.Contains(err.Error(), "grpc: received message larger than max") {
		// raise codec.MaxMessageSize on both sides or chunk the payload
	}
	return err
}

Prevention

Set codec.MaxMessageSize explicitly and identically on client and server.
Chunk or compress payloads expected to exceed the default.
Add payload-size assertions in tests for large-message endpoints.
Check proxy/gateway body-size limits as well.

When it happens

Trigger: Server or client sends a message whose wire length exceeds codec.MaxMessageSize (default small, e.g. 8192 bytes in this codec) while reading a response or request body via ReadBody.

Common situations: Large RPC payloads (big files, bulk exports) exceeding the small default; one side configured with a larger max than the other; proxies buffering responses larger than the client's limit.

Related errors

AI-assisted analysis of micro/go-micro@24529f1404 (2026-09-01). Data as JSON: /api/errors/34930e81140eb7c5. Report an issue: GitHub.

Appendix: source

Thrown at codec/grpc/util.go:38

	}

	// get encoding format e.g compressed
	cf := header[0]

	// get message length
	length := binary.BigEndian.Uint32(header[1:])

	// no encoding format
	if length == 0 {
		return cf, nil, nil
	}

	//
	if int64(length) > int64(maxInt) {
		return cf, nil, fmt.Errorf("grpc: received message larger than max length allowed on current machine (%d vs. %d)", length, maxInt)
	}
	if int(length) > MaxMessageSize {
		return cf, nil, fmt.Errorf("grpc: received message larger than max (%d vs. %d)", length, MaxMessageSize)
	}

	msg := make([]byte, int(length))

	if _, err := r.Read(msg); err != nil {
		if err == io.EOF {
			err = io.ErrUnexpectedEOF
		}
		return cf, nil, err
	}

	return cf, msg, nil
}

func encode(cf uint8, buf []byte, w io.Writer) error {
	header := make([]byte, 5)

	// set compression

View on GitHub (pinned to 24529f1404)