Protobuf — field number out of valid range

Protobuf compilation fails because a field number is 0, exceeds 536870911, or uses reserved numbers 19000-19999 that Protobuf reserves internally.

beginnerdebuggingprotobufserialization

Symptoms

error: Field number 0 is not valid
error: Field number 19000 is reserved
protoc fails with "invalid field number"

Possible causes

A field is declared with number 0, which is invalid in Protobuf
A field uses a number in the reserved 19000-19999 range
A field number exceeds the maximum of 536870911

Diagnosis steps

Check the proto file field numbers

grep -n "= [0-9]*;" proto/file.proto

Interpretation

Identify any field with 0, 19000-19999, or > 536870911.

Run protoc with verbose output

protoc --proto_path=. file.proto 2>&1

Interpretation

The error message names the field and the invalid number.

Root cause

Protobuf field numbers must be 1-536870911 excluding 19000-19999; any other value is rejected by the compiler.

Fix

Change the field number to a valid value between 1 and 536870911, excluding the reserved range, and recompile the proto file.

Verify the fix

Compile the proto file and confirm no errors; verify the generated code includes the field.

Symptom walkthrough

Protobuf compilation fails because a field number is 0, exceeds 536870911, or uses reserved numbers 19000-19999 that Protobuf reserves internally. The error appears in production but may not surface in local development because the conditions that trigger it depend on the deployment environment or runtime configuration. Understanding the full symptom set helps distinguish this issue from similar errors.

Diagnosis in practice

Follow the diagnosis steps in the frontmatter to isolate the cause. Each step includes a command and an interpretation of the output. The goal is to narrow down whether the issue is in the configuration, the runtime, or the application code. Reproduce the error in a minimal setup before applying a fix.

Root cause

Protobuf field numbers must be 1-536870911 excluding 19000-19999; any other value is rejected by the compiler.

Fix

Change the field number to a valid value between 1 and 536870911, excluding the reserved range, and recompile the proto file. After applying the fix, monitor the system to confirm the error does not recur under load or in different environments.

Verification

Compile the proto file and confirm no errors; verify the generated code includes the field. If the verification passes, the fix is confirmed; if not, re-examine the diagnosis steps for missed contributing factors.

Diagnostic commands

Run these commands to reproduce and diagnose the issue:

grep -n "= [0-9]*;" proto/file.proto
protoc --proto_path=. file.proto 2>&1