GoReleaser "release already exists" (422) in CI

GoReleaser tries to create a GitHub release for the tag and the API returns 422 because a release with that tag already exists. This happens on re-runs or when a partial release was left behind.

What this error means

GoReleaser fails with "release already exists" or "422 Validation Failed" naming the existing release for the tag being published.

Terminal

⨯ release failed after 3s
  error=could not create release: POST https://api.github.com/repos/acme/app/releases:
  422 Validation Failed [{Resource:Release Field:tag_name Code:already_exists}]

Common causes

A previous run created the release

A re-run of the same tag, or a failed run that got past release creation, leaves a release GoReleaser will not overwrite by default.

The tag was released manually

A release created by hand or another tool for the same tag blocks GoReleaser from creating its own.

How to fix it

Delete the existing release or retag

Delete the stale GitHub release (and optionally the tag) for that version.
Re-run the release job so GoReleaser creates it fresh.
For a genuinely new release, push a new incremented tag.

Terminal

gh release delete v1.2.3 --yes
git push origin :refs/tags/v1.2.3   # only if retagging

Allow replacing an existing draft release

Configure the release to be recreated on re-run so an existing artifact set is replaced instead of blocking.

.goreleaser.yaml

release:
  mode: replace

How to prevent it

Increment the tag for each release rather than re-releasing a tag.
Clean up failed partial releases before re-running.
Use release.mode: replace if re-runs of the same tag are expected.