buf breaking "Previously present field ... was deleted" in CI

buf breaking diffs the current schema against a baseline (a git ref or BSR module) and fails when it finds a change that breaks compatibility, such as a deleted field, a changed field type, or a renumbered tag. The output names each offending element.

What this error means

buf breaking exits non-zero with one line per change, for example "Previously present field \"2\" with name \"email\" on message \"User\" was deleted." The CI step is gating pull requests against main.

buf

user/v1/user.proto:1:1:Previously present field "2" with name "email" on message "User" was deleted.

Common causes

A field was removed, renumbered, or retyped

Deleting a field, reusing or changing its tag number, or changing its type breaks wire or source compatibility with existing clients.

The change is intended but the baseline is unchanged

Sometimes the break is deliberate (a new major version). buf still flags it because the baseline it compares against has not moved.

How to fix it

Keep compatibility by reserving instead of deleting

Read which field and message buf flagged.
If clients still depend on it, restore the field, or reserved the number and name instead of reusing them.
Re-run buf breaking against the same baseline.

user/v1/user.proto

message User {
  reserved 2;
  reserved "email";
  string id = 1;
}

Version the API when the break is intentional

Put the incompatible schema under a new versioned package so the baseline comparison stays clean for the old one.

Terminal

buf breaking --against '.git#branch=main'

How to prevent it

Reserve removed field numbers and names rather than reusing them.
Roll incompatible changes into a new package version.
Run buf breaking on every PR against the merge base.