microsoft/aspire · error · InvalidOperationException

Generated Deno Dockerfiles do not support '--env-file'…

Error message

Generated Deno Dockerfiles do not support '--env-file' because dotenv files can contain secrets that would be copied into the container image. Use Aspire environment variables or secret parameters, or provide a custom Dockerfile that handles the file securely.

What it means

The generated Deno Dockerfile bakes the build context into the image, so passing --env-file on the Deno command line would copy a dotenv file (which commonly holds secrets) into the container image layers. The library rejects this at build time and directs you to Aspire environment variables or secret parameters instead.

Solutions

Remove the --env-file argument from the Deno command line.
Pass configuration via Aspire environment variables (WithEnvironment) or secret parameters (AddParameter(..., secret: true) / WithEnvironment with a parameter reference).
Provide a custom Dockerfile that injects the env file securely at runtime rather than build time.

Example fix

// before
.WithDeno(deno => deno.WithArgs("--env-file=.env", "run", "main.ts"))
// after
.WithEnvironment("MY_SECRET", builder.AddParameter("my-secret", secret: true))
 .WithDeno(deno => deno.WithArgs("run", "main.ts"))

Defensive patterns

Strategy: validation

Validate before calling

// scan Deno runtime args for --env-file before publishing
if (deno.RuntimeArgs.Any(a => a == "--env-file" || a.StartsWith("--env-file=")))
{
    throw new InvalidOperationException("--env-file is unsupported in generated Deno Dockerfiles; use Aspire environment variables.");
}

Try / catch

try
{
    app.WithDeno(deno => deno.WithArgs("run", "main.ts"));
}
catch (InvalidOperationException ex) when (ex.Message.Contains("--env-file"))
{
    // migrate .env values to WithEnvironment / secret parameters
}

Prevention

Never pass dotenv files via command-line flags into container images.
Use Aspire parameters (secret: true) and WithEnvironment for configuration and secrets.
Audit existing local Deno run scripts for --env-file before adding container publish.

When it happens

Trigger: Adding "--env-file" or "--env-file=..." to the Deno runtime arguments via WithDeno* methods (WithArgs/WithRuntimeArgs on the DenoCommandLineAnnotation), then generating the Dockerfile.

Common situations: A local dev workflow that loads .env via --env-file being carried over to container publish; secrets (.env with API keys) committed next to the app; replacing Aspire-managed environment configuration with a dotenv file.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.JavaScript/DenoHostingExtensions.cs:976

            !string.Equals(packageManager.ExecutableName, "deno", StringComparison.Ordinal))
        {
            throw new InvalidOperationException($"Generated Deno Dockerfiles do not support alternate package manager '{packageManager.ExecutableName}'. Use WithDeno() or provide a custom Dockerfile.");
        }

        if (resource.TryGetLastAnnotation<DenoCommandLineAnnotation>(out var deno) &&
            deno.NodeModulesDirSet &&
            deno.NodeModulesDirMode == DenoNodeModulesDirMode.Manual)
        {
            throw new InvalidOperationException("The 'manual' node_modules mode is not supported by generated Deno Dockerfiles because node_modules is excluded from the build context. Use the 'auto' mode or provide a custom Dockerfile.");
        }

        if (deno is not null)
        {
            if (deno.RuntimeArgs.Any(argument =>
                argument == "--env-file" ||
                argument.StartsWith("--env-file=", StringComparison.Ordinal)))
            {
                throw new InvalidOperationException(
                    "Generated Deno Dockerfiles do not support '--env-file' because dotenv files can contain secrets that would be copied into the container image. Use Aspire environment variables or secret parameters, or provide a custom Dockerfile that handles the file securely.");
            }

            // The Docker build context is the app directory, so a path that is absolute or escapes the app
            // directory is never copied into the image and would break both `deno cache` and the entrypoint.
            ThrowIfPathEscapesDenoBuildContext(deno.ConfigFile, nameof(WithDenoConfig));
            ThrowIfPathEscapesDenoBuildContext(deno.ImportMap, nameof(WithDenoImportMap));
            ThrowIfPathEscapesDenoBuildContext(deno.Lock, nameof(WithDenoLock));
        }
    }

    /// <summary>
    /// Rejects a configured path that would resolve outside the generated Dockerfile's build context.
    /// </summary>
    /// <remarks>
    /// Validation uses the same platform-independent normalizer as the generated Dockerfile. Both <c>/</c> and
    /// <c>\</c> are treated as separators so Windows rooted and UNC paths cannot become absolute only after they
    /// are emitted into the Linux container. Traversal is resolved by depth: <c>config/../deno.json</c> stays

View on GitHub (pinned to 25830f84bd)