microsoft/aspire · error · InvalidOperationException

Deployment state section

Error message

Deployment state section '{section.SectionName}' is missing required value '{name}'.

What it means

Thrown by GetRequiredStateValue when a required key is absent or blank in a section of the persisted sandbox deployment state. The library treats the deployment state file as the source of truth and refuses to continue with an empty required value.

Solutions

  1. Re-run the Azure sandbox deployment so the deployment state is regenerated with all required values.
  2. Inspect the deployment state section in the file and confirm the named key exists and has a non-empty string value.
  3. Verify you are reading the correct DeploymentStateSection; a typo in the section or value name yields this error.
  4. If the state file is stale or from an older schema version, delete it and redeploy the sandbox.

Example fix

// before (state file missing key)
{ "Sandbox": { } }
// after (key present)
{ "Sandbox": { "ResourceGroupName": "rg-sandbox-abc" } }
Defensive patterns

Strategy: validation

Validate before calling

bool HasRequiredValue(DeploymentStateSection section, string name) =>
    section.Data.TryGetValue(name, out var v) && !string.IsNullOrWhiteSpace(v?.GetValue<string>());

Try / catch

try { var v = GetRequiredStateValue(section, name); }
catch (InvalidOperationException ex) { logger.LogError(ex, "Missing deployment state value '{Name}'", name); throw; }

Prevention

When it happens

Trigger: Calling GetRequiredStateValue(section, name) where `section.Data[name]` is null, whitespace, or not a string; e.g. reading outputs like subscription/resource-group names from a section that was never populated.

Common situations: Deployment state file truncated, hand-edited, or written by an older Aspire version with a different schema; provisioning completed but the state section was never written; wrong section name requested.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

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

Appendix: source

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

    {
        var effectiveCancellationToken = cancellationToken ?? context.CancellationToken;
        try
        {
            await client.DeleteDiskImageAsync(scope, diskImageId, effectiveCancellationToken).ConfigureAwait(false);
        }
        catch (Exception ex) when (!throwOnError &&
            (ex is not OperationCanceledException || !effectiveCancellationToken.IsCancellationRequested))
        {
            context.Logger.LogWarning(ex, "Failed to delete sandbox disk image '{DiskImageId}'.", diskImageId);
        }
    }

    private static string GetRequiredStateValue(DeploymentStateSection section, string name)
    {
        var value = section.Data[name]?.GetValue<string>();
        if (string.IsNullOrWhiteSpace(value))
        {
            throw new InvalidOperationException($"Deployment state section '{section.SectionName}' is missing required value '{name}'.");
        }

        return value;
    }

    private static string GetRequiredOutput(AzureBicepResource resource, string name)
    {
        if (!resource.Outputs.TryGetValue(name, out var value) || value is null || string.IsNullOrWhiteSpace(value.ToString()))
        {
            throw new InvalidOperationException($"Azure resource '{resource.Name}' is missing required output '{name}'. Ensure Azure infrastructure provisioning completed successfully.");
        }

        return value.ToString()!;
    }

    internal static AzureDevComputeResourceScope CreateDataPlaneScope(AzureSandboxGroupResource sandboxGroup)
    {
        ArgumentNullException.ThrowIfNull(sandboxGroup);

View on GitHub (pinned to 25830f84bd)