buf "buf.yaml is invalid" configuration error in CI

By Daniel Zoghalchali·Latchkey

buf validates buf.yaml and buf.gen.yaml before executing. An invalid config (wrong version, unknown field, or a v1 key under v2) fails immediately with a decode error naming the offending field.

What this error means

buf fails with "Failure: buf.yaml is invalid" or "buf.gen.yaml is invalid" plus a decode message such as an unknown field or a missing/incorrect version.

Failure: buf.gen.yaml is invalid: decode: unknown field "plugin"
(did you mean "plugins"?) at buf.gen.yaml

Common causes

A v1 config used with a v2 buf (or vice versa)

buf v2 changed several keys; using a v1-style layout with version: v2 or omitting the version produces a decode error.

A typo or unknown field

A misspelled key like plugin instead of plugins, or a value of the wrong type, fails schema validation.

How to fix it

Set the correct version and keys

1. Declare the version that matches your buf CLI (v2 for buf 1.32+).
2. Fix the field name the decode error names.
3. Re-run buf so the config validates.

version: v2
plugins:
  - remote: buf.build/protocolbuffers/go:v1.34.2
    out: gen

Migrate config with buf

Let buf upgrade an older config layout to the current version automatically.

buf config migrate

How to prevent it

• Pin the buf version and keep configs on the matching version.
• Validate config changes with buf build locally before pushing.
• Use buf config migrate when upgrading buf major versions.

Frequently asked questions

Related guides

References

• GitHub Actions documentation