microsoft/aspire · error · InvalidOperationException

Resource ' ' binds volume ' ' to environment variable ' '…

Error message

Resource '{context.Resource.Name}' binds volume '{VolumeName}' to environment variable '{EnvironmentVariableName}', but compute environment '{environment.Name}' does not support volume mounts. The variable would point at a path that is not backed by storage, so anything written there is lost when the workload restarts. Remove the environment variable binding, or target a compute environment that supports volume mounts.

What it means

ThrowIfEnvironmentCannotMount (invoked from ResolvePath in publish mode) checks the resource's compute environment. If that environment does not implement IComputeEnvironmentWithVolumeMounts, binding a volume to an environment variable would produce a variable pointing at a non-existent/unbacked path, so the library throws InvalidOperationException with a detailed remediation message. This prevents silently persisting data to storage that vanishes on restart.

Solutions

Remove the environment-variable binding for the volume on this resource, since the target environment can't back it with storage.
Assign the resource to a compute environment that implements IComputeEnvironmentWithVolumeMounts (e.g. a container-apps/VM-style environment that supports volume mounts).
Switch the resource to use managed/external storage appropriate for the target environment (e.g. a cloud database) instead of a local volume.
Adjust the resource's compute environment assignment via WithComputeEnvironment so the mount is supported.

Example fix

// before
var cache = builder.AddRedis("cache")
    .WithDataVolume("cache-data", "/data")
    .WithEnvironment("CACHE_DIR", volumeMount.Path); // publish target can't mount volumes

// after
// Either drop the env binding, or target a volume-capable compute environment:
var cache = builder.AddRedis("cache")
    .WithDataVolume("cache-data", "/data")
    .WithComputeEnvironment(volumeCapableEnvironment);

Defensive patterns

Strategy: validation

Validate before calling

// Before publish, verify the target compute environment supports volume mounts:
var env = resource.GetComputeEnvironment();
if (env is not IComputeEnvironmentWithVolumeMounts && resource.HasVolumeMounts())
    throw new InvalidOperationException($"Environment '{env?.Name}' cannot back volume mounts for '{resource.Name}'.");

Type guard

static bool SupportsVolumeMounts(IResource resource) =>
    resource.GetComputeEnvironment() is IComputeEnvironmentWithVolumeMounts or null;

Try / catch

try
{
    await distributedApplication.PublishAsync();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("does not support volume mounts"))
{
    logger.LogError(ex, "Target compute environment cannot back a volume binding: {Message}", ex.Message);
}

Prevention

Match resources with volume mounts to compute environments implementing IComputeEnvironmentWithVolumeMounts.
Remove environment-variable bindings to volume paths when targeting volume-less environments.
Prefer managed storage (cloud databases/services) for state when deploying to volume-less compute.

When it happens

Trigger: In publish mode, a resource with a volume mount that is bound to an environment variable (EnvironmentVariableName set) targeting a compute environment (per GetComputeEnvironment()) that lacks volume-mount support — e.g. deploying to a serverless/compute target that has no persistent volume concept.

Common situations: Publishing an app with databases/stateful services that use WithDataVolume plus environment-variable bindings to a compute environment that doesn't support mounts; switching deployment targets (e.g. from a VM/container host to a volume-less environment) without removing volume bindings.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/ApplicationModel/VolumeMountBindingAnnotation.cs:143

    /// real storage.
    /// </summary>
    private void ThrowIfEnvironmentCannotMount(EnvironmentCallbackContext context)
    {
        // Only an environment that consumes ContainerMountAnnotation can back the path handed to the
        // workload. When the environment is known and does not, the variable resolves to ordinary
        // container storage: writes succeed and are then lost on restart. Fail at publish time instead,
        // because nothing downstream surfaces the problem.
        //
        // A null environment means the model has no compute environment, or several with no explicit
        // binding. Those are ambiguous rather than known-unsupported, so stay quiet rather than block a
        // publish that may well be fine.
        if (context.Resource.GetComputeEnvironment() is not { } environment ||
            environment is IComputeEnvironmentWithVolumeMounts)
        {
            return;
        }

        throw new InvalidOperationException(
            $"Resource '{context.Resource.Name}' binds volume '{VolumeName}' to environment variable " +
            $"'{EnvironmentVariableName}', but compute environment '{environment.Name}' does not support volume " +
            $"mounts. The variable would point at a path that is not backed by storage, so anything written there " +
            $"is lost when the workload restarts. Remove the environment variable binding, or target a compute " +
            $"environment that supports volume mounts.");
    }

    private static string ThrowIfNullOrEmpty([NotNull] string? argument, [CallerArgumentExpression(nameof(argument))] string? paramName = null)
    {
        ArgumentException.ThrowIfNullOrEmpty(argument, paramName);
        return argument;
    }
}

View on GitHub (pinned to 25830f84bd)