microsoft/aspire · error · ArgumentException

Unsupported JSON value kind

Error message

Unsupported JSON value kind '{element.ValueKind}'.

What it means

A JsonElement passed as a manifest field has a ValueKind the normalizer does not handle — in practice JsonValueKind.Undefined (or a kind outside the handled set of Null, True, False, Number, Array, Object, String). The library throws an ArgumentException because the JSON value cannot be emitted into the manifest.

Solutions

1. Check element.ValueKind != JsonValueKind.Undefined before passing the JsonElement to WithField
2. Ensure the JsonDocument the element came from is still alive and was parsed successfully without JsonCommentHandling/invalid-JSON leniency that yields Undefined
3. Replace default(JsonElement) placeholders with JsonValueKind.Null ( JsonSerializer.SerializeToElement((object?)null) )

Example fix

// before
using var doc = JsonDocument.Parse(maybeJson);
manifest.WithField("spec.config", doc.RootElement.GetProperty("missing")); // may be Undefined
// after
using var doc = JsonDocument.Parse(maybeJson);
if (doc.RootElement.TryGetProperty("missing", out var el) && el.ValueKind != JsonValueKind.Undefined)
{
    manifest.WithField("spec.config", el);
}

if (element.ValueKind is JsonValueKind.Undefined) throw new InvalidOperationException("JSON element is Undefined and cannot be a manifest field.");

static bool IsWellFormedJsonElement(JsonElement e) => e.ValueKind is not JsonValueKind.Undefined;

try { manifest.WithField(path, element); } catch (ArgumentException ex) when (ex.Message.Contains("Unsupported JSON value kind")) { manifest.WithField(path, (string?)null); }

When it happens

Trigger: Calling WithField with a JsonElement/JsonNode whose ValueKind is Undefined, typically obtained from JsonDocument.Parse of invalid or partial data, default(JsonElement), or a property that was skipped/removed from a JsonDocument.

Common situations: Parsing JSON with JsonDocumentOptions allowing malformed input, reading properties that don't exist, reusing a disposed JsonDocument, or passing default(JsonElement) as a placeholder. JsonNode can also wrap null kinds that degrade to Undefined.

Understand the failure class

Background: "JSON serialization failed", "not JSON serializable", "Failed to serialize": why JSON marshaling errors happen and how to fix them — this error's family across 46 libraries.

Related errors

• Manifest field dictionaries must use string keys.
• Manifest field numeric values must be finite.
• Cannot set nested manifest field
• Expected a non-empty Kubernetes MicroTime value.
• Expected a string token for Kubernetes MicroTime but found

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

Appendix: source

Thrown at src/Aspire.Hosting.Kubernetes/KubernetesManifestResource.cs:231

    {
        using var document = JsonDocument.Parse(node.ToJsonString());

        return NormalizeJsonElement(document.RootElement);
    }

    private static object? NormalizeJsonElement(JsonElement element)
    {
        return element.ValueKind switch
        {
            JsonValueKind.Null => null,
            JsonValueKind.String => element.GetString(),
            JsonValueKind.True => true,
            JsonValueKind.False => false,
            JsonValueKind.Number when element.TryGetInt64(out var longValue) => longValue,
            JsonValueKind.Number => element.GetDouble(),
            JsonValueKind.Array => element.EnumerateArray().Select(NormalizeJsonElement).ToList(),
            JsonValueKind.Object => element.EnumerateObject().ToDictionary(prop => prop.Name, prop => NormalizeJsonElement(prop.Value), StringComparer.Ordinal),
            _ => throw new ArgumentException($"Unsupported JSON value kind '{element.ValueKind}'.", nameof(element))
        };
    }

    private static Dictionary<string, object?> NormalizeDictionary(IDictionary dictionary)
    {
        var result = new Dictionary<string, object?>(StringComparer.Ordinal);

        foreach (DictionaryEntry entry in dictionary)
        {
            if (entry.Key is not string key)
            {
                throw new ArgumentException("Manifest field dictionaries must use string keys.");
            }

            result[key] = NormalizeManifestValue(entry.Value);
        }

        return result;

View on GitHub (pinned to 25830f84bd)