microsoft/aspire · error · DistributedApplicationException

The Rust app ' ' targets ' ', but the default Rust runtime…

Error message

The Rust app '{resource.Name}' targets '{target}', but the default Rust runtime image is not compatible with its target ABI. Configure runtimeImage with WithDockerfileBaseImage before publishing.

What it means

After mapping the cargo target to a container platform, the Rust integration verifies that the default musl runtime image supports the target's ABI (target environment). For Docker's linux/arm platform the default Alpine runtime image only supports musleabi/musleabihf environments, and for other platforms only the plain musl environment. If the target's ABI is not compatible and no custom runtime image was configured via WithDockerfileBaseImage, the library throws when the Dockerfile is finalized for publishing.

Solutions

Supply a runtime image matching the target ABI: call WithDockerfileBaseImage(runtimeImage: "<image for the target ABI>") before publishing.
Configure both images in one WithDockerfileBaseImage(buildImage: ..., runtimeImage: ...) call when both defaults are incompatible — later calls replace the earlier configuration.
Change the cargo target to a musl environment (e.g. x86_64-unknown-linux-musl, aarch64-unknown-linux-musl, or for linux/arm use *-musleabi/musleabihf) so the default Alpine runtime image is compatible.
Provide your own Dockerfile for ABIs the generated Dockerfile cannot support.

Example fix

// before
builder.AddRustApp("worker", "../worker")
    .WithCargoOptions(o => o.WithTarget("aarch64-unknown-linux-gnu"));

// after
builder.AddRustApp("worker", "../worker")
    .WithCargoOptions(o => o.WithTarget("aarch64-unknown-linux-musl")); // musl ABI matches default runtime image
// or keep gnu and set a matching runtime image:
//     .WithDockerfileBaseImage(runtimeImage: "ubuntu:24.04");

Defensive patterns

Strategy: validation

Validate before calling

// Before publishing, check the target ABI against the default runtime image rules
var target = "aarch64-unknown-linux-gnu"; // your WithCargoOptions target
var env = target.Split('-')[^1];
var runtimeOk = env == "musl" || env is "musleabi" or "musleabihf";
if (!runtimeOk)
{
    // configure WithDockerfileBaseImage(runtimeImage: ...) before publishing
}

Try / catch

try
{
    // app host publish/run
}
catch (DistributedApplicationException ex) when (ex.Message.Contains("runtime image is not compatible"))
{
    // surface guidance: configure WithDockerfileBaseImage(runtimeImage: ...) matching the target ABI
}

Prevention

Prefer musl target triples when using the generated Dockerfile; gnu ABIs need a custom runtime image.
For linux/arm targets, verify the exact ABI (musleabi/musleabihf) your runtime image supports.
Set both buildImage and runtimeImage together in one WithDockerfileBaseImage call when leaving the supported matrix.
Run the publish pipeline in CI whenever target triples change.

When it happens

Trigger: Publishing a Rust app whose cargo target ABI mismatches the default runtime image: e.g. WithCargoOptions(o => o.WithTarget("x86_64-unknown-linux-gnu")) (gnu, not musl) or a target environment the Alpine runtime image does not cover, while WithDockerfileBaseImage was never called with a non-null runtimeImage. ResolveContainerTargetPlatform sets defaultRuntimeImageCompatible=false and customRuntimeImageConfigured=false.

Common situations: Using a gnu instead of musl target triple and relying on the generated Dockerfile; picking an unusual ARM ABI (musleabi vs musl) for an embedded board; copying a sample config that sets only buildImage via WithDockerfileBaseImage and not runtimeImage.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Rust/RustHostingExtensions.cs:921

            && (!customBuildImageConfigured || !customRuntimeImageConfigured))
        {
            throw new DistributedApplicationException(
                $"The Rust app '{resource.Name}' targets '{target}', which is not compatible with the default " +
                "musl build and runtime images. Configure both images in a single " +
                "WithDockerfileBaseImage(buildImage: ..., runtimeImage: ...) call before publishing; later calls replace " +
                "the previous configuration.");
        }

        if (!defaultBuildImageCompatible && !customBuildImageConfigured)
        {
            throw new DistributedApplicationException(
                $"The Rust app '{resource.Name}' targets '{target}', but the default Rust build image does not support " +
                $"container target platform '{platform}'. Configure buildImage with WithDockerfileBaseImage before publishing.");
        }

        if (!defaultRuntimeImageCompatible && !customRuntimeImageConfigured)
        {
            throw new DistributedApplicationException(
                $"The Rust app '{resource.Name}' targets '{target}', but the default Rust runtime image is not compatible " +
                "with its target ABI. Configure runtimeImage with WithDockerfileBaseImage before publishing.");
        }

        return platform;
    }

    private static DistributedApplicationException CreateUnsupportedContainerTargetException(
        RustAppResource resource,
        string target)
        => new(
            $"The Rust app '{resource.Name}' targets '{target}', which cannot be mapped to a supported Docker Linux " +
            "container platform. Generated Rust containers support native Linux x86_64, aarch64, 32-bit ARM, " +
            "and 32-bit x86 targets. Use an authored Dockerfile to publish this target.");

    private sealed class RustPublishState
    {
        public ContainerTargetPlatform? TargetPlatform { get; set; }

View on GitHub (pinned to 25830f84bd)