dagger/dagger · error

parsing %q image ref: %w

Error message

parsing %q image ref: %w

What it means

The Python SDK runtime parses the FROM lines of its embedded base/uv Dockerfiles at discovery time to learn the default image references. If `NewImage` (which calls distribution/reference's ParseNormalizedNamed) fails to parse a ref found in those Dockerfiles, extraction aborts with this wrapped error naming the Dockerfile stage.

Source

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

	}
	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 {
					return nil, fmt.Errorf("parsing %q image ref: %w", name, err)
				}

				images[name] = image
			}
		}
	}

	for _, name := range baseImageNames {
		if _, found := images[name]; !found {
			return nil, fmt.Errorf("unable to find %q image ref", name)
		}
	}

	return images, nil
}

View on GitHub (pinned to 82ba2681db)

Solutions

1. Inspect the wrapped inner error to find the offending stage name in the message and fix the FROM line in the corresponding Dockerfile under sdk/python/runtime/images/
2. Ensure no unresolved build args or variables are used as image refs in the embedded Dockerfiles
3. Validate the ref locally, e.g. `docker build` the Dockerfile or run a quick reference.ParseNormalizedNamed check
4. Update/upgrade Dagger if the Dockerfiles in your installed version are corrupted

Example fix

// before
FROM ${BASE_IMAGE} AS base
// after
FROM python:3.12-slim AS base

import re
FROM_RE = re.compile(r'^FROM\s+(\S+)\s+AS\s+(\S+)')
for line in open('sdk/python/runtime/images/base/Dockerfile'):
    m = FROM_RE.match(line.strip())
    if m:
        assert '/' in m.group(1) or m.group(1).count('.') or ':' in m.group(1), f'bad ref: {m.group(1)}'

When it happens

Trigger: A FROM line in sdk/python/runtime/images/base/Dockerfile or images/uv/Dockerfile contains a malformed or empty image reference (e.g. a build arg left unresolved like ${BASE_IMAGE}, or an invalid registry/name/tag), so reference.ParseNormalizedNamed rejects it during NewDiscovery.

Common situations: Dagger SDK maintainers editing the bundled Dockerfiles (renaming stages, templating image names, bumping base images) and producing a ref the Docker parser cannot normalize; it is essentially an internal/CI error, not something module authors cause.

Related errors

• unable to find %q image ref
• %q should exist in scope, but doesn't
• failed to generate function cases for %s: %w
• dagql root is not Query
• parse image repository %q: %w

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