microsoft/aspire · error · DistributedApplicationException

Java application ' ' cannot be published because ' ' is…

Error message

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.

What it means

NormalizeContextRelativePath validates authored paths (e.g. prebuilt jar paths) against the Docker build context, which is the application directory. A rooted path or one containing '..' would require files outside the build context, which are not uploaded to the container build, so it throws DistributedApplicationException at publish time.

Solutions

  1. Move or copy the jar into the application directory and reference it with a relative path.
  2. Remove '..' segments; if the artifact lives in a shared location, copy it into the app directory during your build.
  3. Ensure the path is relative with forward slashes, e.g. "libs/app.jar".

Example fix

// before
.WithJarArtifact("../shared-libs/payments.jar")
// after
.WithJarArtifact("libs/payments.jar"); // jar copied under the app directory
Defensive patterns

Strategy: validation

Validate before calling

var normalized = path.Replace('\\', '/');
if (Path.IsPathRooted(path) || normalized.Split('/').Contains(".."))
    throw new ArgumentException($"{path} must be a relative path inside the application directory (Docker build context)");

Try / catch

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

Prevention

When it happens

Trigger: Calling TryGetPrebuiltJarPath (via Dockerfile generation) with a prebuilt jar path that is absolute ("/libs/app.jar", "D:\jars\app.jar") or that escapes the app directory ("../shared/app.jar").

Common situations: Referencing a jar from a sibling project directory; using an absolute host path for a prebuilt artifact; restructuring directories so the jar now sits above the app directory.

Understand the failure class

Background: Path traversal blocked: "path escapes the workspace" and "outside site root" errors when a path will not stay inside its allowed directory — this error's family across 26 libraries.

Related errors

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

Appendix: source

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

    /// does, rather than only when the build happens to run on Windows.
    /// </remarks>
    private static bool IsWindowsRooted(string path)
        => path.StartsWith('\\')
            || (path.Length >= 2 && char.IsAsciiLetter(path[0]) && path[1] == ':');

    private static string NormalizeContextRelativePath(string authored, string resourceName, string appDirectory, string description)
    {
        // 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(

View on GitHub (pinned to 25830f84bd)