microsoft/aspire · error · DistributedApplicationException

Java application ' ' cannot be published because ' '…

Error message

Java application '{resourceName}' cannot be published because {description} '{authored}' contains whitespace, which a Dockerfile COPY instruction cannot express. Move it to a path without spaces.

What it means

After path-escape checks, NormalizeContextRelativePath rejects any path containing whitespace because the Dockerfile generator emits shell-form COPY instructions whose arguments are separated by spaces with no quoting support. A path like "target/my app.jar" cannot be expressed in the generated Dockerfile, so it throws DistributedApplicationException.

Solutions

Rename the file or directory to remove spaces (e.g. "MyApp.jar", "java-app/").
Adjust your Maven/Gradle build finalName so the produced jar has no spaces.
Copy the artifact to a space-free relative path within the app directory and reference that.

Example fix

// before
.WithJarArtifact("target/My App.jar")
// after
.WithJarArtifact("target/MyApp.jar"); // or set <finalName>MyApp</finalName> in pom.xml

Defensive patterns

Strategy: validation

Validate before calling

if (path.Any(char.IsWhiteSpace))
    throw new ArgumentException($"{path} contains whitespace, which Dockerfile COPY cannot express; rename it without spaces");

Try / catch

try { await PublishAsync(...); } catch (DistributedApplicationException ex) when (ex.Message.Contains("whitespace")) { Console.Error.WriteLine(ex.Message); return 1; }

Prevention

Name projects, output directories, and jars without spaces (set Maven finalName / Gradle archiveBaseName).
Check jar file names produced by CI for spaces from version strings.
Audit resource paths for whitespace before publishing.

When it happens

Trigger: Publishing a Java resource whose prebuilt jar path (via TryGetPrebuiltJarPath/selectArtifact) contains spaces, e.g. "target/My App.jar" or a project directory named "Java App".

Common situations: Project or output directories named with spaces (common on Windows desktops); jar names containing version strings with spaces.

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/00a9617c1a3966f4. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Java/JavaDockerfileGenerator.cs:441

        // Container paths are POSIX even when the AppHost authored a Windows-style relative path.
        var normalized = authored.Replace('\\', '/');

        if (normalized.StartsWith("./", StringComparison.Ordinal))
        {
            normalized = normalized[2..];
        }

        if (IsPathRootedOnAnyPlatform(authored) || normalized.Split('/').Contains(".."))
        {
            throw new DistributedApplicationException(
                $"Java application '{resourceName}' cannot be published because {description} '{authored}' " +
                $"is outside the build context '{appDirectory}'. Only files under the application " +
                "directory are uploaded to the container build.");
        }

        if (normalized.Any(char.IsWhiteSpace))
        {
            throw new DistributedApplicationException(
                $"Java application '{resourceName}' cannot be published because {description} '{authored}' " +
                "contains whitespace, which a Dockerfile COPY instruction cannot express. Move it to a " +
                "path without spaces.");
        }

        return normalized;
    }

    private static JavaBuildTool? DetectBuildToolForPublish(JavaAppResource resource, string appDirectory)
        => JavaBuildToolResolver.Detect(
            appDirectory,
            resource.Name,
            static message => new DistributedApplicationException(message));

    /// <summary>
    /// The JDK the build stage runs on, which is not necessarily the JDK the application targets.
    /// </summary>
    /// <remarks>

View on GitHub (pinned to 25830f84bd)