microsoft/aspire · error · DistributedApplicationException

The OpenTelemetry agent path

Error message

The OpenTelemetry agent path '{authored}' configured on resource '{resource.Name}' points outside the application directory, which is the Docker build context, so it cannot be published. Use a path inside '{resource.WorkingDirectory}', or an absolute path that the base image or a mount provides at runtime.

What it means

TryGetBuildProducedAgentPath normalizes the OpenTelemetry agent path and rejects any path whose segments include '..'. The Docker build context is the application directory, so a path that walks above it can never be COPYed into the image; the generator throws instead of silently rewriting the path.

Solutions

  1. Move the agent jar inside the application directory (resource.WorkingDirectory) and reference it relatively, e.g. "otel/javaagent.jar".
  2. Or use an absolute path that the base image or a runtime mount provides, e.g. "/opt/otel/javaagent.jar".
  3. Remove '..' segments from the path.

Example fix

// before
.WithOtelAgent("../shared-libs/javaagent.jar")
// after
.WithOtelAgent("otel/javaagent.jar"); // jar copied into the app directory
Defensive patterns

Strategy: validation

Validate before calling

var segments = agentPath.Replace('\\', '/').Split('/');
if (segments.Contains(".."))
    throw new ArgumentException("Otel agent path must stay inside the application directory (Docker build context)");

Try / catch

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

Prevention

When it happens

Trigger: Publishing a Java resource whose WithOtelAgent path escapes the app directory, e.g. WithOtelAgent("../shared/javaagent.jar") or "target/../../agents/javaagent.jar".

Common situations: Keeping the agent jar in a shared folder above the project; restructuring solutions so the agent lives outside the app directory; reusing a path authored for local (host) execution where '..' resolved fine.

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

Appendix: source

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

            return false;
        }

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

        // Strip a single leading "./" only. Trimming the '.' and '/' characters as a set would turn
        // "../agents/otel.jar" into "agents/otel.jar" and emit a COPY for a path that was never in the
        // build context, failing the container build with a path the author never wrote.
        if (normalized.StartsWith("./", StringComparison.Ordinal))
        {
            normalized = normalized[2..];
        }

        // The Docker build context is the application directory, so a path that walks above it cannot be
        // copied forward no matter how it is spelled. Say so instead of silently rewriting it.
        if (normalized.Split('/').Any(segment => segment == ".."))
        {
            throw new DistributedApplicationException(
                $"The OpenTelemetry agent path '{authored}' configured on resource '{resource.Name}' " +
                $"points outside the application directory, which is the Docker build context, so it cannot be " +
                $"published. Use a path inside '{resource.WorkingDirectory}', or an absolute path that the base " +
                $"image or a mount provides at runtime.");
        }

        // The Dockerfile builder emits the shell form of COPY, whose arguments are separated by
        // whitespace with no quoted form, so "target/otel agents/javaagent.jar" would copy two paths that
        // do not exist. Naming the problem beats failing later inside the container build.
        if (normalized.Any(char.IsWhiteSpace))
        {
            throw new DistributedApplicationException(
                $"The OpenTelemetry agent path '{authored}' configured on resource '{resource.Name}' " +
                $"contains whitespace, which a Dockerfile COPY instruction cannot express, so it cannot be " +
                $"published. Move the agent to a path without spaces.");
        }

        agentPath = normalized;

View on GitHub (pinned to 25830f84bd)