buf "buf lint" FAILURE rule violation in CI

By Kaveh Alemi·Latchkey

buf lint enforces a rule set (DEFAULT by default) covering naming, packaging, and structure. A FAILURE lists each violation with file, line, and rule id. Fix the proto or, deliberately, relax the rule in buf.yaml.

What this error means

buf lint prints one line per violation ending in a rule id such as FIELD_LOWER_SNAKE_CASE or PACKAGE_DIRECTORY_MATCH, and the job exits 1.

api/v1/user.proto:8:3:Field name "userID" should be lower_snake_case, such as "user_i_d". (FIELD_LOWER_SNAKE_CASE)
api/v1/user.proto:1:1:Files with package "api.v1" must be within a directory "api/v1" relative to root. (PACKAGE_DIRECTORY_MATCH)

Common causes

A proto breaks a rule in the active rule set

The DEFAULT rule set flags issues like non-snake_case field names, package/directory mismatches, or missing suffixes.

buf.yaml enables stricter rules than the code follows

Turning on rule categories beyond DEFAULT (or specific rules) surfaces violations existing protos never satisfied.

How to fix it

Fix the proto to satisfy the rule

1. Read the rule id at the end of each line.
2. Rename fields to lower_snake_case, align package to directory, and so on.
3. Re-run buf lint until it is clean.

// before: string userID = 1;
string user_id = 1;

Scope or ignore a rule deliberately in buf.yaml

If a rule does not fit, exclude specific rules or paths in buf.yaml rather than disabling lint entirely.

version: v2
lint:
  use:
    - DEFAULT
  except:
    - FIELD_LOWER_SNAKE_CASE

How to prevent it

• Run buf lint in a pre-commit hook so violations never reach CI.
• Agree on a rule set and encode it in buf.yaml.
• Use buf lint --error-format=github-actions for inline annotations.

Frequently asked questions

Related guides

References

• GitHub Actions documentation