GoogleContainerTools/skaffold · error

invalid image %q: %w

Error message

invalid image %q: %w

What it means

Skaffold's config validation (validateImageNames) parses every build artifact's imageName with docker.ParseReference and rejects names that are not valid Docker image references. The wrapped inner error from the Docker reference parser explains exactly which part of the name is malformed. It is thrown at config load time so bad image names fail fast before any build runs.

Source

Thrown at pkg/skaffold/schema/validation/validation.go:182

				errs = append(errs, ErrorWithLocation{
					Error: fmt.Errorf("duplicate image %q found in sources %s and %s: artifact image names must be unique across all configurations",
						a.ImageName, prevSource, c.SourceFile),
					Location: curLines,
				})
				errs = append(errs, ErrorWithLocation{
					Error: fmt.Errorf("duplicate image %q found in sources %s and %s: artifact image names must be unique across all configurations",
						a.ImageName, prevSource, c.SourceFile),
					Location: prevLines,
				})
				continue
			}

			seen[a.ImageName] = c.SourceFile
			arMap[a.ImageName] = a
			parsed, err := docker.ParseReference(a.ImageName)
			if err != nil {
				errs = append(errs, wrapWithContext(c, ErrorWithLocation{
					Error:    fmt.Errorf("invalid image %q: %w", a.ImageName, err),
					Location: curLines,
				})...)
				continue
			}

			if parsed.Tag != "" {
				errs = append(errs, wrapWithContext(c, ErrorWithLocation{
					Error:    fmt.Errorf("invalid image %q: no tag should be specified. Use taggers instead: https://skaffold.dev/docs/how-tos/taggers/", a.ImageName),
					Location: curLines,
				})...)
			}

			if parsed.Digest != "" {
				errs = append(errs, wrapWithContext(c, ErrorWithLocation{
					Error:    fmt.Errorf("invalid image %q: no digest should be specified. Use taggers instead: https://skaffold.dev/docs/how-tos/taggers/", a.ImageName),
					Location: curLines,
				})...)
			}

View on GitHub (pinned to a1189de023)

Solutions

1. Read the wrapped inner error to see which character or segment is invalid, then correct the image name in skaffold.yaml
2. Use the standard [registry/]repository[:tag] format, e.g. 'gcr.io/project/name' (tag will be added by taggers)
3. Check that environment/templated values used in the name are defined and expanded correctly
4. Validate the name locally with 'docker tag' or docker's reference parser before committing

Example fix

// before
build:
  artifacts:
    - image: "my app/api"
// after
build:
  artifacts:
    - image: "gcr.io/my-project/my-app"

// Go: validate an image reference before putting it in skaffold config
func isValidImageRef(name string) error {
	_, err := docker.ParseReference(name)
	return err
}

if err := isValidImageRef(img); err != nil {
	return fmt.Errorf("fix image name %q before running skaffold: %w", img, err)
}

When it happens

Trigger: A skaffold.yaml artifact has build.artifacts[].image.name that fails docker reference parsing: empty name, illegal characters, wrong registry/port syntax, or more than one tag/colon segment.

Common situations: Typo in the image name (e.g. 'my app/api'), stray quotes or whitespace, using 'localhost:5000:5000/repo' style port confusion, or templated names left unresolved ({{.Var}} not substituted).

Related errors

• parsing image name: %w
• %q running container image %q errored during run with status
• docker deployment not supported alongside cluster deployment
• verify command expects non-zero number of test cases
• INIT_DOCKER_NETWORK_CONTAINER_DOES_NOT_EXIST

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