GoogleContainerTools/skaffold · error

parsing image %v: %w

Error message

parsing image %v: %w

What it means

NewBuildEnvOpts prepares the environment for build lifecycle hooks. It first parses the image string into a Docker reference (repo, tag) with docker.ParseReference. If the image string is not a valid container image reference, the parse error is wrapped as 'parsing image %v: %w'.

Source

Thrown at pkg/skaffold/hooks/build.go:40

	"fmt"
	"io"
	"path/filepath"

	"github.com/GoogleContainerTools/skaffold/v2/pkg/skaffold/docker"
	"github.com/GoogleContainerTools/skaffold/v2/pkg/skaffold/output"
	"github.com/GoogleContainerTools/skaffold/v2/pkg/skaffold/schema/latest"
)

// BuildRunner creates a new runner for pre-build and post-build lifecycle hooks
func BuildRunner(d latest.BuildHooks, opts BuildEnvOpts) Runner {
	return buildRunner{BuildHooks: d, opts: opts}
}

// NewBuildEnvOpts returns `BuildEnvOpts` required to create a `Runner` for build lifecycle hooks
func NewBuildEnvOpts(a *latest.Artifact, image string, pushImage bool) (BuildEnvOpts, error) {
	ref, err := docker.ParseReference(image)
	if err != nil {
		return BuildEnvOpts{}, fmt.Errorf("parsing image %v: %w", image, err)
	}

	w, err := filepath.Abs(a.Workspace)
	if err != nil {
		return BuildEnvOpts{}, fmt.Errorf("determining build workspace directory for image %v: %w", a.ImageName, err)
	}
	return BuildEnvOpts{
		Image:        image,
		PushImage:    pushImage,
		ImageRepo:    ref.Repo,
		ImageTag:     ref.Tag,
		BuildContext: w,
	}, nil
}

type buildRunner struct {
	latest.BuildHooks
	opts BuildEnvOpts

View on GitHub (pinned to a1189de023)

Solutions

1. Inspect the image string in the error message and correct its format (lowercase name, valid tag/digest)
2. Verify the builder actually produced a non-empty image name/tag before hooks run
3. Validate the reference locally with 'docker tag <image> <image>' to see the parser complaint
4. If the image comes from a previous build step, fix the upstream artifact image name in skaffold.yaml

Example fix

// before
err := hooks.NewBuildEnvOpts(artifact, "My Image:v1!", pushImage)
// after
err := hooks.NewBuildEnvOpts(artifact, "registry.example.com/my-image:v1", pushImage)

func validImageRef(image string) bool {
    _, err := docker.ParseReference(image)
    return err == nil && image != ""
}
if !validImageRef(image) { return fmt.Errorf("invalid image %q", image) }
opts, err := hooks.NewBuildEnvOpts(a, image, push)

opts, err := hooks.NewBuildEnvOpts(a, image, push)
if err != nil {
    if strings.HasPrefix(err.Error(), "parsing image") {
        return fmt.Errorf("image %q is not a valid docker reference", image)
    }
    return err
}

When it happens

Trigger: Invoking a build hook runner (via NewBuildEnvOpts) with an image value that is empty, contains invalid characters, has an invalid tag/digest, or an unparseable registry portion — anything rejected by docker's reference parser.

Common situations: A custom build hook configured for an artifact whose produced image string is malformed; image names with uppercase characters or illegal characters like spaces; empty image produced by a failed/incomplete builder; tag containing invalid characters (e.g. '+', leading '-').

Related errors

• parsing reference %q: %w
• INIT_DOCKER_NETWORK_INVALID_MODE
• INIT_DOCKER_NETWORK_INVALID_CONTAINER_NAME
• cannot call Run with empty container config
• parsing tag %q: %w

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