# INTERNAL: grpc: protobuf unknown field encountered: field number 12345

- **ID:** `grpc/grpc-protobuf-unknown-field`
- **Domain:** grpc
- **Category:** encoding_error
- **Verification:** ai_generated
- **Fix Rate:** 90%

## Root Cause

Server received a protobuf message containing a field number that is not defined in the .proto schema, often due to version mismatch between client and server.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| protobuf 25.3 | active | — | — |
| grpc-go 1.62.0 | active | — | — |
| grpc-java 1.60.0 | active | — | — |
| buf 1.28.0 | active | — | — |

## Workarounds

1. **Synchronize the .proto files between client and server. Run:
  buf breaking --against .git
  to detect breaking changes. Regenerate code for both sides:
  protoc --go_out=. --go-grpc_out=. *.proto
  Or use Buf to manage versioning:
  buf generate --template buf.gen.yaml** (90% success)
   ```
   Synchronize the .proto files between client and server. Run:
  buf breaking --against .git
  to detect breaking changes. Regenerate code for both sides:
  protoc --go_out=. --go-grpc_out=. *.proto
  Or use Buf to manage versioning:
  buf generate --template buf.gen.yaml
   ```
2. **If the unknown field is intentional (e.g., forward compatibility), use protojson or custom parsing to explicitly handle unknown fields. In gRPC-Go, set:
  import "google.golang.org/protobuf/encoding/protojson"
  opts := protojson.MarshalOptions{AllowPartial: true}
  But prefer updating the schema to include the field.** (80% success)
   ```
   If the unknown field is intentional (e.g., forward compatibility), use protojson or custom parsing to explicitly handle unknown fields. In gRPC-Go, set:
  import "google.golang.org/protobuf/encoding/protojson"
  opts := protojson.MarshalOptions{AllowPartial: true}
  But prefer updating the schema to include the field.
   ```

## Dead Ends

- **** — This hides the symptom but does not fix the root cause; data loss may occur if important fields are ignored. (70% fail)
- **** — Unknown field handling is a proto3 feature; older versions may still reject or silently drop fields, leading to data corruption. (85% fail)