microsoft/aspire · error · DistributedApplicationException

JavaScript app resource

Error message

JavaScript app resource '{resource.Name}' is configured to run script '{runScript.ScriptName}'{argsClause}, but publish is using the existing Dockerfile '{dockerfileBuildAnnotation.DockerfilePath}'. An existing Dockerfile entrypoint cannot be changed automatically from runScriptName or WithRunScript. Remove or rename the Dockerfile so Aspire can generate one, or call PublishAsDockerFile(...) and set the container entrypoint explicitly.

What it means

At publish time Aspire detected both a run-script configuration (WithRunScript/runScriptName) and a user-authored existing Dockerfile (DockerfileBuildAnnotation with a DockerfilePath). Aspire cannot safely rewrite the ENTRYPOINT of a hand-written Dockerfile to the package-manager script, so it throws instead of silently producing an image that ignores your run script.

Solutions

Remove or rename the existing Dockerfile so Aspire generates one that honors the run script.
Call PublishAsDockerFile(...) and set the container entrypoint explicitly (WithEntrypoint).
Remove the WithRunScript call if the Dockerfile's own entrypoint already runs the right command.

Example fix

// before
builder.AddViteApp("frontend", "./frontend")
    .PublishAsDockerFile(c => c.DockerfilePath = "./Dockerfile")
    .WithRunScript("start"); // conflicts
// after
builder.AddViteApp("frontend", "./frontend")
    .PublishAsDockerFile(c => c.DockerfilePath = "./Dockerfile")
    .WithEntrypoint("./entrypoint.sh"); // explicit entrypoint for existing Dockerfile

Defensive patterns

Strategy: validation

Validate before calling

var usesExistingDockerfile = File.Exists(Path.Combine(resource.WorkingDirectory, "Dockerfile"));
if (usesExistingDockerfile && usesRunScript)
    throw new InvalidOperationException("Existing Dockerfile conflicts with WithRunScript; set an explicit entrypoint.");

Try / catch

try { builder.PublishAsDockerFile(); }
catch (DistributedApplicationException ex) when (ex.Message.Contains("existing Dockerfile"))
{
    // rename/remove the Dockerfile or set an explicit entrypoint, then retry
}

Prevention

Do not mix WithRunScript with a committed Dockerfile in the same project.
Name custom Dockerfiles explicitly and set an explicit entrypoint via PublishAsDockerFile.
Decide once per project: Aspire-generated Dockerfile (run scripts) or custom Dockerfile (explicit entrypoint).

When it happens

Trigger: Calling WithRunScript (or passing runScriptName/args) on a JavaScript resource published via an existing Dockerfile without setting an explicit container entrypoint.

Common situations: Adding a Dockerfile to a project that previously relied on Aspire's generated Dockerfile; the default 'Dockerfile' filename in the project directory is now picked up; switching to a custom Dockerfile without removing run-script configuration.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.JavaScript/JavaScriptHostingExtensions.cs:1982

            !string.Equals(runScript.ScriptName, DefaultJavaScriptRunScriptName, StringComparison.Ordinal) ||
            runScript.Args is { Length: > 0 };

        if (!hasExplicitRunScript)
        {
            return;
        }

        // Include the args in the message when they are the trigger, so the user can see why
        // a default-named script (e.g. "dev") still produced a conflict.
        var argsClause = runScript.Args is { Length: > 0 }
            ? $" with args [{string.Join(", ", runScript.Args)}]"
            : string.Empty;

        // Existing Dockerfiles are user-authored, so Aspire cannot safely assume that replacing
        // their entrypoint with a package-manager script will work for the image shape.
        // If the user provides an explicit container entrypoint above, honor it; otherwise fail
        // instead of silently publishing an image that ignores the requested run script.
        throw new DistributedApplicationException(
            $"JavaScript app resource '{resource.Name}' is configured to run script '{runScript.ScriptName}'{argsClause}, but publish is using the existing Dockerfile '{dockerfileBuildAnnotation.DockerfilePath}'. " +
            "An existing Dockerfile entrypoint cannot be changed automatically from runScriptName or WithRunScript. " +
            "Remove or rename the Dockerfile so Aspire can generate one, or call PublishAsDockerFile(...) and set the container entrypoint explicitly.");
    }

    /// <summary>
    /// Adds a Vite app to the distributed application builder.
    /// </summary>
    /// <param name="builder">The <see cref="IDistributedApplicationBuilder"/> to add the resource to.</param>
    /// <param name="name">The name of the Vite app.</param>
    /// <param name="appDirectory">The path to the directory containing the Vite app.</param>
    /// <param name="runScriptName">The name of the script that runs the Vite app. Defaults to "dev".</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
    /// <ats-returns>The resource builder.</ats-returns>
    /// <remarks>
    /// <example>
    /// The following example creates a Vite app using npm as the package manager.
    /// <code lang="csharp">

View on GitHub (pinned to 25830f84bd)