microsoft/aspire · error · InvalidOperationException

AppHost:DeploymentStatePathSha256 is required to isolate…

Error message

AppHost:DeploymentStatePathSha256 is required to isolate Azure sandbox ownership between AppHosts.

What it means

GetStableAppHostIdentity reads the 'AppHost:DeploymentStatePathSha256' configuration value, which hashes the deployment-state path to isolate sandbox ownership between AppHosts. If the value is missing or empty, an InvalidOperationException is thrown because sandbox ownership cannot be determined safely.

Solutions

  1. Run the deployment through the standard AppHost/publish pipeline so the key is populated
  2. Set configuration key 'AppHost:DeploymentStatePathSha256' to the deployment state path hash before deploying
  3. Update the AppHost runtime if it predates this configuration contract

Example fix

// before
configuration["AppHost:DeploymentStatePathSha256"] unset
// after
configuration["AppHost:DeploymentStatePathSha256"] = Convert.ToHexString(System.IO.Hashing.XxHash3.Hash(KnownDeploymentStatePath));
Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrEmpty(configuration["AppHost:DeploymentStatePathSha256"]))
    throw new InvalidOperationException("AppHost:DeploymentStatePathSha256 must be configured before sandbox deployment.");

Try / catch

try { DeploySandbox(...); } catch (InvalidOperationException ex) when (ex.Message.Contains("DeploymentStatePathSha256")) { /* run via standard AppHost pipeline or set the key */ }

Prevention

When it happens

Trigger: Running Azure sandbox deployment outside the normal AppHost pipeline (which normally injects AppHost:DeploymentStatePathSha256), or with a configuration source that drops this key.

Common situations: Custom host builders or test harnesses not wiring AppHost configuration; invoking deployment publishing APIs directly; older AppHost runtime not setting the new key.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.Sandboxes/AzureSandboxContainerDeployment.cs:2002

    private static void SetPendingLegacyDeploymentCleanup(
        DeploymentStateSection stateSection,
        JsonObject? pendingDeploymentCleanup)
    {
        if (pendingDeploymentCleanup is null)
        {
            stateSection.Data.Remove("PendingLegacyDeploymentCleanup");
        }
        else
        {
            stateSection.Data["PendingLegacyDeploymentCleanup"] = pendingDeploymentCleanup.DeepClone();
        }
    }

    internal static string GetStableAppHostIdentity(IConfiguration configuration)
    {
        return configuration["AppHost:DeploymentStatePathSha256"] is { Length: > 0 } deploymentStatePathHash
            ? deploymentStatePathHash
            : throw new InvalidOperationException("AppHost:DeploymentStatePathSha256 is required to isolate Azure sandbox ownership between AppHosts.");
    }

    internal static string CreateDeploymentSecurityFingerprint(
        string immutableImageReference,
        IReadOnlyList<SandboxEndpoint> endpoints,
        IReadOnlyList<AzureDevComputeIdentitySetting>? identitySettings,
        AzureDevComputeSandboxEgressPolicy egressPolicy)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(immutableImageReference);
        ArgumentNullException.ThrowIfNull(egressPolicy);

        return new JsonObject
        {
            ["ImageReference"] = immutableImageReference,
            ["Endpoints"] = new JsonArray(
                endpoints
                    .OrderBy(static endpoint => endpoint.Name, StringComparer.Ordinal)
                    .Select(static endpoint => (JsonNode)new JsonObject

View on GitHub (pinned to 25830f84bd)