GoReleaser ".goreleaser.yaml unknown field" unmarshal error in CI

GoReleaser parses .goreleaser.yaml into a typed config. An unknown key, a typo, or a field moved between schema versions causes a strict unmarshal error before the build begins.

What this error means

GoReleaser fails to load config with "yaml: unmarshal errors" and "field <name> not found in type config.<Type>", pointing at the offending key.

Terminal

⨯ only configurations files on version: 2 are supported, yours is version: 0,
  please update your configuration
  error=yaml: unmarshal errors:
    line 12: field archive not found in type config.Project

Common causes

A typo or removed field

A key such as archive (now archives) or a misspelled option is not in the schema, so strict parsing rejects it.

A field from a different schema version

Config written for an older GoReleaser uses keys that moved or were renamed in the current version.

How to fix it

Validate and correct the field

Run goreleaser check locally to see the exact offending key and line.
Fix the typo or move the field to its current location in the schema.
Re-run goreleaser check until it passes.

Terminal

goreleaser check

Pluralize renamed sections

Several top-level keys are plural in current schemas; for example use archives: not archive:.

.goreleaser.yaml

archives:
  - formats: [tar.gz]

How to prevent it

Run goreleaser check in CI before the release job.
Pin the GoReleaser version so the schema does not shift unexpectedly.
Consult the config reference when upgrading GoReleaser.