What causes "failed to parse image address %s: %w" in dagger/dagger?

Fix the reference to valid Docker syntax: [registry/]repository[:tag][@digest], lowercase repository.

failed to parse image address %s: %w

Error message

failed to parse image address %s: %w

What it means

Host.containerImage takes an image name and normalizes it via the Docker reference parser. If the provided string isn't a valid image reference (bad characters, malformed tag/digest, empty), parsing fails and the parse error is wrapped with this message including the original name.

Source

Thrown at core/schema/host.go:762

			if err != nil {
				return nil, false, err
			}
			matched = matched || childMatched
			if target != nil {
				return target, true, nil
			}
		}
		return nil, matched, nil

	default:
		return nil, false, fmt.Errorf("unsupported host image media type %s", desc.MediaType)
	}
}

func (s *hostSchema) containerImage(ctx context.Context, parent dagql.ObjectResult[*core.Host], args hostContainerArgs) (inst dagql.Result[*core.Container], err error) {
	refName, err := reference.ParseNormalizedNamed(args.Name)
	if err != nil {
		return inst, fmt.Errorf("failed to parse image address %s: %w", args.Name, err)
	}
	refName = reference.TagNameOnly(refName)

	query, err := core.CurrentQuery(ctx)
	if err != nil {
		return inst, err
	}
	bk, err := query.Engine(ctx)
	if err != nil {
		return inst, fmt.Errorf("failed to get engine client: %w", err)
	}

	imageReader, err := bk.ReadImage(ctx, refName.String())
	if err != nil {
		return inst, err
	}

	if imageReader.ContentStore != nil && imageReader.ImagesStore != nil {

View on GitHub (pinned to 82ba2681db)

Solutions

Fix the reference to valid Docker syntax: [registry/]repository[:tag][@digest], lowercase repository.
Strip URL schemes and whitespace before passing the image name.
If the name is dynamic, validate/normalize it first (reference.ParseNormalizedNamed equivalent or regex).

Example fix

// before
dag.host().containerImage("https://registry.example.com/MyApp:latest")
// after
dag.host().containerImage("registry.example.com/myapp:latest")

Defensive patterns

Strategy: validation

Validate before calling

const refRe = /^(?:[a-z0-9]+(?:[._-][a-z0-9]+)*(?::\d+)?\/)?[a-z0-9]+(?:[._-][a-z0-9]+)*(?:\/[a-z0-9]+(?:[._-][a-z0-9]+)*)*(?::[\w][\w.-]{0,127})?(?:@[A-Za-z][A-Za-z0-9]*(?::[0-9a-fA-F]{32,})?)?$/
if (!refRe.test(name)) throw new Error(`invalid image reference: ${name}`)

Type guard

function isValidImageRef(name) { return typeof name === "string" && /^[a-z0-9.\/:_@-]+$/.test(name.trim()) && !name.includes("::") && !/^https?:\/\//.test(name) }

Try / catch

try { await dag.host().containerImage(name) } catch (e) { if (String(e).includes("failed to parse image address")) throw new Error(`bad image ref '${name}': use [registry/]repo[:tag][@digest], lowercase`); throw e }

Prevention

Always use lowercase repo names and no URL schemes.
Trim/validate dynamically built image names before calling the API.
Let Dagger normalize names; don't pre-append defaults like :latest incorrectly.

When it happens

Trigger: Calling Host.containerImage with an invalid reference string, e.g. "my image", "repo::tag", a name with uppercase characters, or a URL with a scheme like "https://registry/img".

Common situations: Passing a full registry URL instead of an image reference, interpolating whitespace or newlines into the name, using uppercase repository names, or typos like double colons in tag/digest.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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