microsoft/aspire · error · JsonException

JSON Patch array index

Error message

JSON Patch array index '{indexText}' is invalid for an array with {count} elements.

What it means

ParseArrayIndex validates the final segment of a JSON Patch array path. The segment must be all ASCII digits, parse as a non-negative int, and be within bounds; unless allowEnd is set (i.e. the '-' token case for append), the index must also be strictly less than the array length. Any violation throws this JsonException with the index text and array size.

Solutions

Check the array Count before patching and clamp/adjust the index
Use the '-' segment with an 'add' operation to append instead of computing Count
Fix the segment to an existing index or a property name if the target is actually an object

Example fix

// before
new JsonPatchOperation("add", "/containers/" + containers.Count, item) // invalid: index == Count
// after
new JsonPatchOperation("add", "/containers/-", item) // '-' appends per RFC 6902

Defensive patterns

Strategy: validation

Validate before calling

static bool IsValidArrayIndex(JsonArray array, string segment, bool allowEnd = false) {
    if (segment == "-") return allowEnd;
    return segment.All(char.IsAsciiDigit) && int.TryParse(segment, out var i) && i >= 0 && i < array.Count;
}

Try / catch

try { patcher.Apply(doc, operations); }
catch (JsonException ex) when (ex.Message.Contains("array index")) {
    logger.LogWarning(ex, "Bad array index in patch path; use '-' to append");
}

Prevention

Use the '-' segment to append rather than computing Count
Recheck array length after any operation that mutates the array
Never reuse hardcoded indexes across resource revisions

When it happens

Trigger: Patching '/containers/5' when the array has 3 elements; passing a non-numeric segment like 'name' where an array index is expected; using index equal to Count where append ('-') is required.

Common situations: Hardcoded indexes after the array shrank; off-by-one errors treating index==Count as valid outside of 'add'; addressing arrays by property-style names.

Related errors

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

Appendix: source

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

                target.RemoveAt(index);
                break;
            case "replace":
                target[index] = value?.DeepClone();
                break;
        }
    }

    private static int ParseArrayIndex(string indexText, int count, bool allowEnd)
    {
        if (indexText.Length == 0 ||
            (indexText.Length > 1 && indexText[0] == '0') ||
            !indexText.All(char.IsAsciiDigit) ||
            !int.TryParse(indexText, NumberStyles.None, CultureInfo.InvariantCulture, out var index) ||
            index < 0 ||
            index > count ||
            (!allowEnd && index == count))
        {
            throw new JsonException($"JSON Patch array index '{indexText}' is invalid for an array with {count} elements.");
        }

        return index;
    }
}

View on GitHub (pinned to 25830f84bd)