What causes "parsing image name: %w" in GoogleContainerTools/skaffold?

Fix image.ImageName to a valid Docker reference (lowercase, no spaces, valid registry/repo:tag form)

parsing image name: %w

Error message

parsing image name: %w

What it means

When the Tagger returns an empty tag (meaning the image name already carries the tag), GenerateFullyQualifiedImageName validates image.ImageName alone with docker.ParseReference. If the bare image name is not a parseable Docker reference, it returns 'parsing image name:'.

Source

Thrown at pkg/skaffold/tag/tag.go:49

type Tagger interface {
	// GenerateTag generates a tag for an artifact.
	GenerateTag(ctx context.Context, image latest.Artifact) (string, error)
}

// GenerateFullyQualifiedImageName resolves the fully qualified image name for an artifact.
// The workingDir is the root directory of the artifact with respect to the Skaffold root,
// and imageName is the base name of the image.
func GenerateFullyQualifiedImageName(ctx context.Context, t Tagger, image latest.Artifact) (string, error) {
	tag, err := t.GenerateTag(ctx, image)
	if err != nil {
		return "", fmt.Errorf("generating tag: %w", err)
	}

	// Tag is already set in imageName
	if tag == "" {
		_, err := docker.ParseReference(image.ImageName)
		if err != nil {
			return "", fmt.Errorf("parsing image name: %w", err)
		}
		return image.ImageName, nil
	}

	fullImageName := fmt.Sprintf("%v:%v", image.ImageName, tag)
	_, err = docker.ParseReference(fullImageName)
	if err != nil {
		return "", fmt.Errorf("parsing image name: %w", err)
	}
	return fullImageName, nil
}

View on GitHub (pinned to a1189de023)

Solutions

Fix image.ImageName to a valid Docker reference (lowercase, no spaces, valid registry/repo:tag form)
Ensure the tagger isn't returning an empty tag unintentionally if you expected a generated tag to be appended
Sanitize/normalize the image name before passing the artifact to the tagger
Validate with a quick parse: `docker tag <name> tmp` or a regex for valid repo names

Example fix

// before
image.ImageName = "My App/service"
// after
image.ImageName = "my-app/service"

Defensive patterns

Strategy: validation

Validate before calling

if image.ImageName == "" {
    return errors.New("artifact image name must not be empty")
}
if _, err := reference.ParseAnyReference(image.ImageName); err != nil {
    return fmt.Errorf("invalid image name %q: %w", image.ImageName, err)
}

Type guard

func isValidImageName(name string) bool {
    _, err := reference.ParseNormalizedNamed(name)
    return err == nil
}

Try / catch

tag, err := tag.GenerateFullyQualifiedImageName(ctx, tagger, image)
if err != nil && strings.Contains(err.Error(), "parsing image name") {
    return fmt.Errorf("fix imageName in skaffold.yaml (lowercase, no spaces): %w", err)
}

Prevention

Use lowercase repo names with no spaces or special chars
Validate artifact image names against the Docker reference grammar in CI
Never pass empty image names programmatically

When it happens

Trigger: GenerateFullyQualifiedImageName called with a Tagger that yields an empty tag and an image.ImageName that docker reference parsing rejects — e.g. containing invalid characters, uppercase with a registry that fails validation, or an empty string.

Common situations: Image names built dynamically with spaces or illegal characters; empty imageName passed programmatically; typos in skaffold.yaml artifact image names like 'My App/service'.

Related errors

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