microsoft/aspire · error · DistributedApplicationException

The OpenTelemetry agent path

Error message

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.

What it means

TryGetBuildProducedAgentPath rejects an OpenTelemetry agent path containing whitespace because the Dockerfile builder emits shell-form COPY whose arguments are space-separated with no quoted form; "target/otel agents/javaagent.jar" would copy two nonexistent paths. The generator throws at publish time instead of failing later inside the container build.

Solutions

  1. Rename the agent file/directory to remove spaces (e.g. "otel/javaagent.jar").
  2. Copy the agent to a space-free relative path inside the app directory and point WithOtelAgent at it.
  3. Update the script or pipeline that downloads the agent to use a space-free target directory.

Example fix

// before
.WithOtelAgent("target/otel agents/javaagent.jar")
// after
.WithOtelAgent("target/otel/javaagent.jar");
Defensive patterns

Strategy: validation

Validate before calling

if (agentPath.Any(char.IsWhiteSpace))
    throw new ArgumentException("Otel agent path must not contain whitespace; the generated Dockerfile COPY cannot express it");

Try / catch

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

Prevention

When it happens

Trigger: Publishing a Java resource configured via WithOtelAgent with a path containing spaces, e.g. WithOtelAgent("target/otel agents/javaagent.jar").

Common situations: Agent jar placed in a directory named with spaces; downloaded agent archives extracted into folders like "New Folder"; Windows-style directory names with spaces carried into the resource config.

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

Appendix: source

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

        }

        // 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;

        return agentPath.Length > 0;
    }

    /// <summary>
    /// The build-tool-specific pieces of the container build.
    /// </summary>
    /// <param name="Tool">The build tool that produces the JAR.</param>
    /// <param name="Args">The resolved arguments passed to the build tool.</param>
    /// <param name="BuildCommand">The shell command that runs the build.</param>
    /// <param name="SelectArtifactCommand">The shell command that copies the produced JAR to a fixed path.</param>
    /// <param name="ToolHome">The container path the build tool treats as its home directory.</param>

View on GitHub (pinned to 25830f84bd)