buf breaking "previously present ... was deleted" in CI

By Daniel Zoghalchali·Latchkey

This is the most common buf breaking violation: removing a field, message, enum value, or RPC that existing clients still depend on. Reserving the removed field number and name preserves wire compatibility.

What this error means

buf breaking reports "Previously present field \"N\" with name \"x\" on message \"M\" was deleted." or the equivalent for a message, enum value, or RPC.

api/v1/order.proto:1:1:Previously present RPC "CancelOrder" on service "OrderService"
was deleted.
Failure: breaking changes detected.

Common causes

A field or RPC was removed outright

Deleting a field number or an RPC removes something clients may still call or read, so buf flags it as breaking.

A whole message or enum was renamed or dropped

Renaming is a delete plus an add at the schema level, which breaks references and generated clients.

How to fix it

Reserve removed field numbers and names

1. Instead of deleting a field, mark its number and name reserved.
2. This prevents reuse and keeps the wire format compatible.
3. Re-run buf breaking; a reserved field is not a breaking deletion.

message Order {
  reserved 4;
  reserved "coupon_code";
}

Deprecate instead of deleting an RPC

Keep the RPC and mark it deprecated so clients migrate before it is ever removed in a new version.

rpc CancelOrder(CancelOrderRequest) returns (CancelOrderResponse) {
  option deprecated = true;
}

How to prevent it

• Reserve field numbers and names on every removal.
• Deprecate RPCs and messages before deleting them in a new version.
• Gate merges on buf breaking against main.

Frequently asked questions

Related guides

References

• GitHub Actions documentation