dagger/dagger · error

invalid image ref %q

Error message

invalid image ref %q

What it means

NewImage() parses a Docker image reference with distribution/reference's ParseNormalizedNamed. Normally the parse error is returned directly; the 'invalid image ref %q' wrapper fires when parsing succeeds but yields a nil named reference, indicating a structurally unusable (empty) input that slipped through. Called by parseBaseImage, UnmarshalJSON, and extractImages.

Source

Thrown at sdk/python/runtime/image.go:102

		return nil
	}
	img, err := NewImage(ref)
	if err != nil {
		return err
	}
	i.named = img.named
	return nil
}

// NewImage parses a string into a named reference transforming a familiar
// name from Docker UI to a fully qualified reference.
func NewImage(ref string) (Image, error) {
	named, err := reference.ParseNormalizedNamed(ref)
	if err != nil {
		return Image{}, err
	}
	if named == nil {
		return Image{}, fmt.Errorf("invalid image ref %q", ref)
	}
	return Image{named: named}, nil
}

// extractImages reads from the bundled Dockerfile to extract the default docker
// image references.
func extractImages() (map[string]Image, error) {
	images := make(map[string]Image)
	for _, dockerfile := range []string{baseDockerfile, uvDockerfile} {
		lines := strings.Split(dockerfile, "\n")

		for _, line := range lines {
			if matches := fromLineRegex.FindStringSubmatch(strings.TrimSpace(line)); matches != nil {
				ref := matches[1]
				name := matches[2]

				image, err := NewImage(ref)
				if err != nil {

View on GitHub (pinned to 82ba2681db)

Solutions

1. Check the %q value in the message to find the offending config/env source and supply a valid image reference.
2. Ensure any image-setting env var or dagger.json field is non-empty (e.g. python:3.12-slim-bookworm).
3. Reinstall the dagger CLI if the embedded Dockerfile is damaged/empty.
4. Validate image refs before passing them to the runtime (see validationCode).

Example fix

// before
cfg.BaseImage = os.Getenv("DAGGER_BASE_IMAGE") // ""
// after
cfg.BaseImage = os.Getenv("DAGGER_BASE_IMAGE")
if cfg.BaseImage == "" { cfg.BaseImage = "python:3.12-slim-bookworm" }

// Go: validate an image ref before handing it to the runtime
if strings.TrimSpace(ref) == "" {
    return fmt.Errorf("image ref is empty; set DAGGER_BASE_IMAGE or a default")
}

img, err := runtime.NewImage(ref)
if err != nil {
    if strings.Contains(err.Error(), "invalid image ref") {
        return fmt.Errorf("image ref %q is invalid/empty; check env and config: %w", ref, err)
    }
    return err
}

When it happens

Trigger: Passing an empty string or a string that parses to a nil named ref to NewImage — e.g. an unset environment variable or missing Dockerfile FROM line feeding parseBaseImage/extractImages, or an empty image field during JSON unmarshal.

Common situations: Missing BASE_IMAGE-style env override; bundled Dockerfile with an empty image placeholder; dagger.json or API payload carrying an empty/blank image string; typos in image names that fail normalization.

Related errors

• empty image
• invalid ID
• load persisted %s snapshot link: zero result ID
• engine volume address must not include user information
• volume address must not include a fragment

AI-assisted analysis of dagger/dagger@82ba2681db (2026-09-05). Data as JSON: /api/errors/6a3535ecb42b9ef5. Report an issue: GitHub.