microsoft/aspire · error · DistributedApplicationException

Java application ' ' cannot be published because it uses…

Error message

Java application '{builder.Resource.Name}' cannot be published because it uses the Dockerfile in '{builder.Resource.WorkingDirectory}' and its OpenTelemetry agent path '{authored}' is relative to the build output. Aspire copies a build-produced agent into the image only in the Dockerfile it generates. Copy the agent in your Dockerfile and pass its path inside the image to WithOtelAgent, for example WithOtelAgent("/opt/otel/javaagent.jar").

What it means

When publishing to a container, a build-produced OTel agent is copied into the image only by the Dockerfile Aspire generates. If the developer supplied their own Dockerfile (JavaAuthoredDockerfileAnnotation) and the configured agent path is relative to the build output, nothing places the agent in the image and the JVM fails at startup. The library throws a DistributedApplicationException at publish time with instructions to copy the agent yourself and pass an in-image path.

Solutions

  1. Copy the agent jar into the image in your own Dockerfile (COPY/ADD) and pass its in-image path: WithOtelAgent("/opt/otel/javaagent.jar")
  2. Let Aspire generate the Dockerfile (remove the authored Dockerfile) if the build-output agent path should work
  3. Bake the agent path handling into the Dockerfile and reference only absolute in-image paths

Example fix

// before
.WithOtelAgent("target/otel/javaagent.jar") // authored Dockerfile never copies this
// after (in Dockerfile)
COPY target/otel/javaagent.jar /opt/otel/javaagent.jar
// after (in AppHost)
.WithOtelAgent("/opt/otel/javaagent.jar")
Defensive patterns

Strategy: validation

Validate before calling

if (resource.HasAnnotationOfType<JavaAuthoredDockerfileAnnotation>() && !Path.IsPathRooted(agentPath))
{
    // authored Dockerfile + build-output-relative agent path will fail at publish; use an in-image absolute path and COPY the agent in the Dockerfile
}

Type guard

var usesAuthoredDockerfile = resource.HasAnnotationOfType<JavaAuthoredDockerfileAnnotation>();

Try / catch

try { Publish(); }
catch (DistributedApplicationException ex) when (ex.Message.Contains("OpenTelemetry agent path"))
{
    // copy the agent in your Dockerfile and call WithOtelAgent("/opt/otel/javaagent.jar")
}

Prevention

When it happens

Trigger: WithOtelAgent called with a relative build-output path on a Java resource that uses an authored Dockerfile, then publishing (container build) the app.

Common situations: Custom Dockerfile projects adding the OTel agent with the default inference path; migrating a generated-Dockerfile project to a hand-written one without updating the agent path.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Java/JavaHostingExtensions.cs:1254

            }

            var authored = ResolveOtelAgentPath(builder.Resource, agent);

            string resolved;

            if (context.ExecutionContext.IsRunMode)
            {
                resolved = Path.GetFullPath(Path.Combine(builder.Resource.WorkingDirectory, authored));
            }
            else if (JavaDockerfileGenerator.TryGetBuildProducedAgentPath(builder.Resource, out _))
            {
                // /app/agent.jar is where the generated Dockerfile copies the agent to. When the
                // developer wrote the Dockerfile, nothing put it there, and a JVM told to load an agent
                // that is not in the image dies during VM initialization with "Error opening zip file or
                // JAR manifest missing" — which says nothing about the cause.
                if (builder.Resource.HasAnnotationOfType<JavaAuthoredDockerfileAnnotation>())
                {
                    throw new DistributedApplicationException(
                        $"Java application '{builder.Resource.Name}' cannot be published because it uses " +
                        $"the Dockerfile in '{builder.Resource.WorkingDirectory}' and its OpenTelemetry " +
                        $"agent path '{authored}' is relative to the build output. Aspire copies a " +
                        $"build-produced agent into the image only in the Dockerfile it generates. Copy " +
                        $"the agent in your Dockerfile and pass its path inside the image to " +
                        $"{nameof(WithOtelAgent)}, for example WithOtelAgent(\"/opt/otel/javaagent.jar\").");
                }

                resolved = JavaDockerfileGenerator.ContainerAgentPath;
            }
            else
            {
                resolved = authored;
            }

            AppendJavaToolOptions(context.EnvironmentVariables, [$"-javaagent:{resolved}"]);
        });
    }

View on GitHub (pinned to 25830f84bd)