microsoft/aspire · error · InvalidDataException

' ' must contain a JSON array of non-empty strings.

Error message

'{ClaimedSectionsProperty}' must contain a JSON array of non-empty strings.

What it means

Aspire's FileDeploymentStateManager persists per-deployment state (including which pipeline sections have been claimed) in a state file. When loading, it reads the ClaimedSectionsProperty value and deserializes it as a JSON array of strings; if the stored value is null, not valid JSON for a string array, or contains null/whitespace entries, the state file is considered corrupt and this InvalidDataException is thrown to fail fast rather than silently re-run or skip claimed deployment sections.

Solutions

  1. Delete or rename the corrupted deployment state file (e.g. under the deployment state directory) and re-run the deployment so a fresh state is written.
  2. Verify the code writing ClaimedSectionsProperty serializes a List<string> of non-empty names via JsonSerializer, not a raw joined string or null.
  3. If a custom IResource or state provider supplies the value, ensure GetValue returns valid JSON text like ["sectionA","sectionB"].
  4. Upgrade/downgrade so the writing and reading Aspire versions agree on the state-file schema.

Example fix

// before: writes an invalid claimed-sections value
state["ClaimedSections"] = string.Join(",", sections);
// after
state["ClaimedSections"] = JsonSerializer.Serialize(sections);
Defensive patterns

Strategy: validation

Validate before calling

if (JsonSerializer.Deserialize<string?[]>(claimedValue) is not { } names || names.Any(string.IsNullOrWhiteSpace))
    throw new InvalidDataException("ClaimedSections state is corrupt; delete the state file and retry.");

Type guard

bool IsValidClaimedSections(string?[]? names) => names is not null && !names.Any(string.IsNullOrWhiteSpace);

Try / catch

try { LoadClaimedSections(state); } catch (InvalidDataException ex) { logger.LogWarning(ex, "Corrupt deployment state; resetting claimed sections."); state.Remove(ClaimedSectionsProperty); }

Prevention

When it happens

Trigger: Calling the section-claiming load path when the saved state file's ClaimedSectionsProperty contains: a JSON null, a non-array JSON value (e.g. a plain string or object), an array containing null or whitespace-only strings, or corrupt/truncated JSON written by a previous crashed run.

Common situations: A deployment state file edited by hand, a state file produced by an older or newer Aspire version with a different schema, a partially-written state file after a crashed or killed deployment, or a custom state manager writing the property in the wrong format.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/Pipelines/Internal/FileDeploymentStateManager.cs:779

        var currentState = migrationState[CurrentStateProperty] switch
        {
            null => null,
            JsonValue stateValue => JsonNode.Parse(stateValue.GetValue<string>())?.AsObject()
                ?? throw new InvalidDataException($"'{CurrentStateProperty}' must contain a JSON object."),
            _ => throw new InvalidDataException($"'{CurrentStateProperty}' must be a JSON string.")
        };

        return new(legacyFallbackDisabled, legacyStateSnapshot, claimedSectionNames, currentState);
    }

    private static string[] ParseClaimedSectionNames(JsonValue claimedSectionsValue)
    {
        var claimedSectionNames = JsonSerializer.Deserialize<string?[]>(
            claimedSectionsValue.GetValue<string>());
        if (claimedSectionNames is null ||
            claimedSectionNames.Any(string.IsNullOrWhiteSpace))
        {
            throw new InvalidDataException(
                $"'{ClaimedSectionsProperty}' must contain a JSON array of non-empty strings.");
        }

        return [.. claimedSectionNames.Select(static sectionName => sectionName!)];
    }

    private Task SaveMigrationStateAsync(string canonicalStatePath, CancellationToken cancellationToken) =>
        SaveMigrationStateAsync(
            canonicalStatePath,
            _currentState,
            _legacyStateSnapshot,
            _claimedSectionNames,
            _legacyFallbackDisabled,
            cancellationToken);

    private static Task SaveMigrationStateAsync(
        string canonicalStatePath,
        JsonObject currentState,

View on GitHub (pinned to 25830f84bd)