buf "buf format --diff" check failure in CI

By Kaveh Alemi·Latchkey

buf format enforces a canonical proto style. In CI, buf format --diff --exit-code prints the required changes and exits non-zero when any file is unformatted. Running buf format -w locally fixes it.

What this error means

A formatting gate fails: buf format prints a unified diff of the changes it would make and exits non-zero, listing the unformatted proto files.

--- api/v1/user.proto
+++ api/v1/user.proto (formatted)
@@ -6,3 +6,3 @@
-  string  user_id=1;
+  string user_id = 1;
Error: Process completed with exit code 1.

Common causes

A proto was not formatted before commit

Manual edits left spacing or ordering that differs from buf canonical style, which the CI diff check flags.

No formatting step in the local workflow

Without a pre-commit buf format -w, unformatted protos reach CI and fail the gate.

How to fix it

Format in place and commit

1. Run buf format -w to rewrite files to canonical style.
2. Commit the formatted protos.
3. Push so buf format --diff --exit-code passes.

buf format -w
git add . && git commit -m "buf format"

Keep the check read-only in CI

CI should verify formatting without rewriting; keep --diff --exit-code so it fails rather than mutating the tree.

buf format --diff --exit-code

How to prevent it

• Run buf format -w in a pre-commit hook.
• Keep the CI check as --diff --exit-code so it only verifies.
• Agree on buf format as the single source of proto style.

Frequently asked questions

Related guides

References

• GitHub Actions documentation