Go buf "breaking change detected" - Fix in CI

By Daniel Zoghalchali·Latchkey

buf breaking compares your protos against a baseline and fails on changes that break consumers - renumbered fields, removed fields, changed types. The gate protects deployed clients from silent incompatibility.

What this error means

CI fails with buf breaking errors listing field or type changes against a baseline branch or image. A proto was edited in a way that breaks compatibility.

api/v1/user.proto:12:3:Field "1" with name "id" on message "User" changed type from "string" to "int64".

Common causes

Field type or number changed

Changing a field tag or type breaks wire compatibility with existing clients.

Field or message removed

Deleting a field that clients still read is a breaking change.

How to fix it

Make the change additive

1. Keep existing field numbers and types; add new fields with new numbers instead.
2. Reserve removed field numbers rather than reusing them.

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

Bump the package version deliberately

1. For a genuine breaking change, introduce a new versioned package (e.g. v2) rather than mutating v1.

package api.v2;

How to prevent it

• Only make additive proto changes within a version.
• Reserve removed field numbers and names.
• Cut a new versioned package for intentional breaking changes.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation