goreleaser/goreleaser · error

failed to process build flag template '%s': %w

Error message

failed to process build flag template '%s': %w

What it means

docker.build_flag_templates are Go templates applied before invoking docker buildx build; the rendered strings become build flags. This error means one template failed to evaluate, so goreleaser cannot construct the docker build command. The failing template text is embedded in the message.

Source

Thrown at internal/pipe/docker/docker.go:365

			return nil, fmt.Errorf("failed to execute image template '%s': %w", imageTemplate, err)
		}
		if image == "" {
			continue
		}

		images = append(images, image)
	}

	return images, nil
}

func processBuildFlagTemplates(ctx *context.Context, docker config.Docker) ([]string, error) {
	//nolint:prealloc
	var buildFlags []string
	for _, buildFlagTemplate := range docker.BuildFlagTemplates {
		buildFlag, err := tmpl.New(ctx).Apply(buildFlagTemplate)
		if err != nil {
			return nil, fmt.Errorf("failed to process build flag template '%s': %w", buildFlagTemplate, err)
		}
		buildFlags = append(buildFlags, buildFlag)
	}
	return buildFlags, nil
}

func dockerPush(ctx *context.Context, image *artifact.Artifact) error {
	log.WithField("image", image.Name).Info("pushing")

	docker := artifact.MustExtra[config.Docker](*image, dockerConfigExtra)
	skip, err := tmpl.New(ctx).Apply(docker.SkipPush)
	if err != nil {
		return err
	}
	if strings.TrimSpace(skip) == "true" {
		return pipe.Skip("docker.skip_push is set: " + image.Name)
	}
	if strings.TrimSpace(skip) == "auto" && ctx.Semver.Prerelease != "" {

View on GitHub (pinned to f5edd73956)

Solutions

1. Fix the field name/syntax indicated by the wrapped error.
2. Replace unavailable context fields with literal values or environment lookups that exist.
3. Validate config with `goreleaser check` and dry-run with `goreleaser build --snapshot`.

Example fix

// before
build_flag_templates:
  - "--build-arg=VERSION={{ .BadField }}"
// after
build_flag_templates:
  - "--build-arg=VERSION={{ .Version }}"

for _, t := range cfg.BuildFlagTemplates {
    if _, err := tmpl.New(ctx).Apply(t); err != nil {
        return fmt.Errorf("bad build flag template %q: %w", t, err)
    }
}

defer func() {
    if r := recover(); r != nil { /* not applicable; wrap release() */ }
}()
if err := release(); err != nil && strings.Contains(err.Error(), "build flag template") {
    // correct the template in goreleaser.yaml
}

When it happens

Trigger: A build_flags entry templated with a key absent from the context, or containing invalid template syntax; commonly used with --build-arg flags like KEY={{ .Env.SOMETHING }} where the env var handling template function errors.

Common situations: Referencing .Env vars not set (in strict contexts), misspelled fields, or copied build_flag_templates from docs that assume extra context fields.

Related errors

• failed to execute image template '%s': %w
• invalid dockerfile: %w
• invalid images: %w
• invalid tags: %w
• invalid labels: %w

AI-assisted analysis of goreleaser/goreleaser@f5edd73956 (2026-09-05). Data as JSON: /api/errors/58c4eba7897f31a8. Report an issue: GitHub.