What causes "invalid digest format" in microsoft/aspire?

Use a sha256 digest: convert the image reference to the form myrepo/myapp@sha256: .

microsoft/aspire · error · ArgumentOutOfRangeException

invalid digest format

Error message

invalid digest format

What it means

When the image reference passed to WithImage contains a digest, the library requires the digest to use the sha256: algorithm prefix. Any other digest format (e.g. sha512: or a bare hex string) triggers this ArgumentOutOfRangeException naming the image parameter.

Solutions

Use a sha256 digest: convert the image reference to the form myrepo/myapp@sha256:<64-hex-chars>.
Get the correct sha256 digest from the registry (e.g. docker inspect or crane digest).
If only tag pinning is needed, drop the digest and use the tag parameter or WithImageSHA256 with the hex portion.
exampleFix placeholder

Example fix

// before
.WithImage("myrepo/myapp@sha512:deadbeef...");
// after
.WithImage("myrepo/myapp@sha256:8d4f3a5b...");

Defensive patterns

Strategy: validation

Validate before calling

var parsed = ContainerReferenceParser.Parse(image);
if (parsed.Digest is { } digest && !digest.StartsWith("sha256:", StringComparison.Ordinal))
    throw new ArgumentException($"Digest '{digest}' must use the sha256: algorithm prefix.", nameof(image));

Try / catch

try
{
    resource.WithImage(image);
}
catch (ArgumentOutOfRangeException ex) when (ex.Message == "invalid digest format")
{
    // Replace with a sha256 digest and retry
}

Prevention

Only use sha256 digests when pinning images.
Fetch digests with 'docker inspect' or 'crane digest' to guarantee the sha256: prefix.
Never hand-strip the 'sha256:' prefix from an image reference.

When it happens

Trigger: Calling WithImage with a reference like "myrepo/myapp@sha512:..." or "myrepo/myapp@abcdef0123" (digest without the sha256: prefix).

Common situations: Copying image references that use non-sha256 algorithms; hand-editing image strings and dropping the 'sha256:' prefix; registries or tooling that emit other digest algorithms.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/f6bffa95576aafa2. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs:450

            ? $"{parsedReference.Registry}/{parsedReference.Image}"
            : parsedReference.Image;

        if (builder.Resource.Annotations.OfType<ContainerImageAnnotation>().LastOrDefault() is { } imageAnnotation)
        {
            imageAnnotation.Image = parsedRegistryAndImage;
        }
        else
        {
            imageAnnotation = new ContainerImageAnnotation { Image = parsedRegistryAndImage };
            builder.Resource.Annotations.Add(imageAnnotation);
        }

        if (parsedReference.Digest is { })
        {
            const string prefix = "sha256:";
            if (!parsedReference.Digest.StartsWith(prefix, StringComparison.Ordinal))
            {
                throw new ArgumentOutOfRangeException(nameof(image), parsedReference.Digest, "invalid digest format");
            }

            var digest = parsedReference.Digest[prefix.Length..];
            imageAnnotation.SHA256 = digest;
        }
        else
        {
            imageAnnotation.Tag = parsedReference.Tag ?? tag ?? "latest";
        }

        // If there's a DockerfileBuildAnnotation with an image name/tag, clear them
        // so that the user's explicit image preference is respected
        if (builder.Resource.Annotations.OfType<DockerfileBuildAnnotation>().SingleOrDefault() is { } buildAnnotation)
        {
            buildAnnotation.ImageName = null;
            buildAnnotation.ImageTag = null;
        }

View on GitHub (pinned to 25830f84bd)