gRPC New Added 8 September 2026

gRPC: INVALID_ARGUMENT (code 3)

The server understood the request and rejected the field values. Because protobuf 3 has no required fields and unset scalars deserialise to zero values, a client that forgot to set a field sends a syntactically valid message that fails validation on arrival.

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

Quick fix

# Print what you are actually sending
grpcurl -d '{"page_size":0}' -vv host:443 pkg.Service/Method

# Distinguish unset from zero with a wrapper or optional
message Query {
  optional int32 page_size = 1;   // proto3 optional gives you has_page_size()
}

# Validate in one place with protovalidate
import "buf/validate/validate.proto";
int32 page_size = 1 [(buf.validate.field).int32 = {gte: 1, lte: 100}];

How to diagnose gRPC errors

Every gRPC call ends with a status code, and the code tells you which layer failed. UNAVAILABLE and INTERNAL are transport: the connection, the proxy or the HTTP/2 stream, not your handler. UNAUTHENTICATED, PERMISSION_DENIED and UNIMPLEMENTED mean the request arrived and was rejected before your logic ran. INVALID_ARGUMENT, FAILED_PRECONDITION and ABORTED are your service answering deliberately. The distinction matters most for retries: UNAVAILABLE and ABORTED are safe to retry, FAILED_PRECONDITION and INVALID_ARGUMENT never are, and retrying them turns one bad request into a storm.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

Read the code and the message together. grpcurl -vv prints the status, the message and any google.rpc error details the server attached, which is far more than most client libraries surface by default.
Establish whether the call reached your handler at all. Log at the first line of the method: if nothing appears, the failure is in the transport, the proxy or an interceptor, and reading your business logic is wasted effort.
Enable the runtime's own transport logging. GRPC_GO_LOG_SEVERITY_LEVEL=info GRPC_GO_LOG_VERBOSITY_LEVEL=2 for Go, or GRPC_VERBOSITY=debug GRPC_TRACE=http,call_error for the C based implementations, exposes HTTP/2 resets and name resolution that the status code hides.
Check that HTTP/2 survives the whole path. Any load balancer that terminates at layer 7 without HTTP/2 support, or an idle timeout shorter than your keepalive, produces stream resets that surface as INTERNAL or UNAVAILABLE on a service that is perfectly healthy.
Confirm both sides were generated from the same .proto. A method rename, a package change or a stale generated file gives UNIMPLEMENTED, and grpcurl list against a server with reflection enabled settles it in one command.
For anything size or time related, remember the limits are enforced per side: the 4 MB receive limit, the client deadline and the server's max connection age each belong to one peer, so raising one alone often just moves the failure.

Tools worth reaching for

grpcurl
grpc_health_probe
GRPC_GO_LOG_SEVERITY_LEVEL / GRPC_TRACE
buf lint && buf breaking
Wireshark or tcpdump with HTTP/2 decoding
Envoy access logs

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

grpc.io

Related gRPC errors

See all 10 gRPC errors →

Browse other categories

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.