microsoft/aspire · error · JsonException

JSON Patch path segment

Error message

JSON Patch path segment '{segment}' does not exist.

What it means

GetParent resolves each intermediate segment of a JSON Patch path. When a segment names a property that does not exist on the current JsonObject (or is not a valid array index), traversal stops and this JsonException identifies the first missing segment. Per RFC 6902, intermediate path segments must exist.

Solutions

  1. Add the missing intermediate object with an 'add' operation before the failing operation
  2. Correct the segment spelling/path to match the document's actual shape
  3. Verify the property exists with TryGetPropertyValue before patching

Example fix

// before
new JsonPatchOperation("replace", "/metadata/labels/app", "web") // 'labels' missing
// after
new JsonPatchOperation("add", "/metadata/labels", new JsonObject()),
new JsonPatchOperation("add", "/metadata/labels/app", "web")
Defensive patterns

Strategy: validation

Validate before calling

static bool SegmentExists(JsonNode node, string segment) => node switch {
    JsonObject o => o.TryGetPropertyValue(segment, out _),
    JsonArray a => int.TryParse(segment, out var i) && i >= 0 && i < a.Count,
    _ => false
};

Try / catch

try { patcher.Apply(doc, operations); }
catch (JsonException ex) when (ex.Message.Contains("does not exist")) {
    logger.LogWarning(ex, "Patch path segment missing; add the intermediate object first");
}

Prevention

When it happens

Trigger: Calling Apply with a path like '/spec/template/metadata' where 'spec' or 'template' is absent from the document.

Common situations: Typos in patch paths; patching a resource whose schema lacks the expected section (e.g. no 'annotations' map yet); copying patch paths between resource kinds with different schemas.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

                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)