GoogleContainerTools/skaffold · error

couldn't parse image tag: %w

Error message

couldn't parse image tag: %w

What it means

The image tag string produced by opts.Tag could not be parsed by EnvTags, which extracts environment-variable-style tag references. Build aborts early before any Docker API call so a malformed tag never reaches the daemon. The underlying parse error is wrapped for context.

Source

Thrown at pkg/skaffold/docker/image.go:342

}

func (l *localDaemon) CheckCompatible(a *latest.DockerArtifact) error {
	if len(a.Secrets) > 0 || a.SSH != "" {
		return fmt.Errorf("docker build options, secrets and ssh, require BuildKit - set `useBuildkit: true` in your config, or run with `DOCKER_BUILDKIT=1`")
	}
	return nil
}

// Build performs a docker build and returns the imageID.
func (l *localDaemon) Build(ctx context.Context, out io.Writer, workspace string, artifact string, a *latest.DockerArtifact, opts BuildOptions) (string, error) {
	log.Entry(ctx).Debugf("Running docker build: context: %s, dockerfile: %s", workspace, a.DockerfilePath)

	if err := l.CheckCompatible(a); err != nil {
		return "", err
	}
	imageInfoEnv, err := EnvTags(opts.Tag)
	if err != nil {
		return "", fmt.Errorf("couldn't parse image tag: %w", err)
	}
	buildArgs, err := EvalBuildArgsWithEnv(opts.Mode, workspace, a.DockerfilePath, a.BuildArgs, opts.ExtraBuildArgs, imageInfoEnv)
	if err != nil {
		return "", fmt.Errorf("unable to evaluate build args: %w", err)
	}

	// Like `docker build`, we ignore the errors
	// See https://github.com/docker/cli/blob/75c1bb1f33d7cedbaf48404597d5bf9818199480/cli/command/image/build.go#L364
	authConfigs, _ := DefaultAuthHelper.GetAllAuthConfigs(ctx)

	buildCtx, buildCtxWriter := io.Pipe()
	go func() {
		err := CreateDockerTarContext(ctx, buildCtxWriter,
			NewBuildConfig(workspace, artifact, a.DockerfilePath, buildArgs), l.cfg)
		if err != nil {
			buildCtxWriter.CloseWithError(fmt.Errorf("creating docker context: %w", err))
			return
		}

View on GitHub (pinned to a1189de023)

Solutions

1. Inspect the tag value passed in BuildOptions.Tag and fix its format (valid `name:tag` reference)
2. Check the tagger configuration in skaffold.yaml (template, envTemplate) for typos or unset environment variables
3. Run skaffold with debug logging to see the exact tag string being generated

Example fix

// before (custom tagger producing invalid tag)
tagPolicy:
  envTemplate:
    template: "{{.BREAKING_ENV}}"
// after
tagPolicy:
  envTemplate:
    template: "{{.IMAGE_NAME}}:{{.VERSION}}"

if tag == "" || strings.ContainsAny(tag, " \t") {
	return fmt.Errorf("invalid image tag: %q", tag)
}
if _, err := docker.EnvTags(tag); err != nil {
	return fmt.Errorf("invalid tag before build: %w", err)
}

imageID, err := daemon.Build(ctx, out, ws, artifact, a, opts)
if err != nil && strings.Contains(err.Error(), "couldn't parse image tag") {
	return fmt.Errorf("fix BuildOptions.Tag (%q): %w", opts.Tag, err)
}

When it happens

Trigger: Calling localDaemon.Build with BuildOptions.Tag containing a string EnvTags cannot parse (e.g. invalid characters, missing/malformed tag portion, unexpected format produced by a custom tagger or templating misconfiguration in skaffold.yaml).

Common situations: A custom tagger template (e.g. {{.TAG}} placeholders) renders an empty or invalid tag; a date/git tagger emits characters invalid for image names; a user passes a hand-written tag with spaces or uppercase in the wrong place via tooling.

Related errors

• couldn't parse image tag %s %w
• parsing image name for registry: %w
• removing unused default args: %w
• parsing tag %q: %w
• %q running container image %q errored during run with status

AI-assisted analysis of GoogleContainerTools/skaffold@a1189de023 (2026-09-05). Data as JSON: /api/errors/7de84ad24d033288. Report an issue: GitHub.