microsoft/aspire · error · JsonException

JSON Patch path segment

Error message

JSON Patch path segment '{segment}' refers to a null value.

What it means

While resolving a patch path's parent, GetParent indexes into a JsonArray for a segment. If the element at that index is JSON null, the traversal cannot continue and the library throws this JsonException naming the offending segment. It distinguishes 'element exists but is null' from 'segment missing'.

Solutions

  1. Remove the null element or replace it with an object before applying the patch
  2. Rewrite the path to target an existing, non-null element
  3. Use an 'add' operation with the '-' index to append instead of addressing a null slot

Example fix

// before
array[2] = null; // then patching /items/2/name fails
// after
array[2] = new JsonObject { ["name"] = "placeholder" };
Defensive patterns

Strategy: validation

Validate before calling

static bool ArrayElementExists(JsonArray array, int index) => index >= 0 && index < array.Count && array[index] is not null;

Try / catch

try { patcher.Apply(doc, operations); }
catch (JsonException ex) when (ex.Message.Contains("refers to a null value")) {
    logger.LogWarning(ex, "Patch path hit a null array element; sanitize the array first");
}

Prevention

When it happens

Trigger: A patch path like '/containers/2/name' where containers[2] is JSON null — typically when the array holds explicit null placeholders.

Common situations: Arrays that were pre-sized with nulls; deserialized documents where list entries were nulled by a previous transform or merge.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/Dcp/JsonPatch.cs:229

            default:
                throw new JsonException("A JSON Patch path can only traverse objects and arrays.");
        }

        return current;
    }

    private static JsonNode GetParent(JsonNode? current, string[] segments)
    {
        var parent = current ?? throw new JsonException("A JSON Patch path cannot traverse a null value.");

        for (var index = 0; index < segments.Length - 1; index++)
        {
            var segment = segments[index];
            parent = parent switch
            {
                JsonObject jsonObject when jsonObject.TryGetPropertyValue(segment, out var child) && child is not null => child,
                JsonArray jsonArray => jsonArray[ParseArrayIndex(segment, jsonArray.Count, allowEnd: false)]
                    ?? throw new JsonException($"JSON Patch path segment '{segment}' refers to a null value."),
                _ => throw new JsonException($"JSON Patch path segment '{segment}' does not exist."),
            };
        }

        return parent;
    }

    private static void ApplyToObject(JsonObject target, string operation, string propertyName, JsonNode? value)
    {
        switch (operation)
        {
            case "add":
                target[propertyName] = value?.DeepClone();
                break;
            case "remove":
                if (!target.Remove(propertyName))
                {
                    throw new JsonException($"JSON Patch remove path refers to missing property '{propertyName}'.");

View on GitHub (pinned to 25830f84bd)