buf "buf breaking" FAILURE against a baseline in CI

By Daniel Zoghalchali·Latchkey

buf breaking compares your protos against a baseline (often main) and fails on any wire- or source-incompatible change. The FAILURE lists exactly which fields, messages, or services broke compatibility.

What this error means

buf breaking prints violations like a deleted field or changed type against the --against target, ending with a non-zero exit.

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

Common causes

A backward-incompatible schema change

Deleting a field, changing its type, or renumbering it breaks existing clients, which buf breaking flags against the baseline.

The change is intentional but the baseline was not bumped

A deliberate major-version break still fails until the comparison target or versioned package moves.

How to fix it

Keep changes backward compatible

1. Do not delete or renumber fields; reserve removed field numbers instead.
2. Add new fields with new numbers rather than repurposing old ones.
3. Re-run buf breaking against the baseline until it passes.

message User {
  reserved 2;              // was: string email = 2;
  reserved "email";
  string primary_email = 5;
}

Point --against at the right baseline

Compare against the main branch so the check reflects merged state, not a stale local ref.

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

How to prevent it

• Reserve deleted field numbers and names, never reuse them.
• Version breaking changes in a new package (api.v2) instead of mutating v1.
• Run buf breaking on every pull request against main.

Frequently asked questions

Related guides

References

• GitHub Actions documentation