microsoft/aspire · error · JsonException

JSON Patch operation

Error message

JSON Patch operation '{operation}' requires a 'value' property.

What it means

For 'add' and 'replace' JSON Patch operations, RFC 6902 requires a 'value' property. ApplyOperation throws a JsonException when an operation other than 'remove' is applied without a value, since there is nothing to insert or substitute.

Solutions

Always include a "value" property in 'add' and 'replace' operations, using "value": null explicitly if null is intended.
Configure the patch serializer to not drop null values (e.g. DefaultIgnoreCondition = Never for patch docs).
Use 'remove' instead of 'replace' with an absent value when deletion is the intent.
Validate patch documents before applying them to catch missing 'value' early.

Example fix

// before
[ { "op": "replace", "path": "/spec/replicas" } ]
// after
[ { "op": "replace", "path": "/spec/replicas", "value": 3 } ]

Defensive patterns

Strategy: validation

Validate before calling

bool HasRequiredValues(JsonNode patch) =>
    patch.AsArray().All(op =>
    {
        var name = op["op"]!.GetValue<string>();
        return name == "remove" || op.AsObject().ContainsKey("value");
    });

Try / catch

try { patch.Apply(target); }
catch (JsonException ex) when (ex.Message.Contains("requires a 'value' property"))
{
    logger.LogError(ex, "Patch op missing 'value': {Message}", ex.Message);
}

Prevention

Always serialize "value": null explicitly instead of dropping null members.
Use 'remove' rather than value-less 'replace' for deletions.
Configure JsonSerializerOptions with DefaultIgnoreCondition = Never for patch documents.

When it happens

Trigger: Applying { "op": "add", "path": "/spec/env/KEY" } with no "value" member, or a 'replace' whose value was dropped during serialization, via the DCP resource update path.

Common situations: Patch producers that omit 'value' when it is null (serializers with IgnoreNullValues dropping JsonValue null); hand-written patches forgetting the value; schema drift between producer and consumer.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

                '0' => '~',
                '1' => '/',
                _ => throw new JsonException($"JSON Pointer segment '{segment}' contains an invalid escape."),
            });
        }

        return result.ToString();
    }

    private static JsonNode? ApplyOperation(JsonNode? current, string operation, string[] segments, bool hasValue, JsonNode? value)
    {
        if (operation is not ("add" or "remove" or "replace"))
        {
            throw new JsonException($"JSON Patch operation '{operation}' is not supported.");
        }

        if (operation is not "remove" && !hasValue)
        {
            throw new JsonException($"JSON Patch operation '{operation}' requires a 'value' property.");
        }

        if (segments.Length == 0)
        {
            return operation switch
            {
                "remove" => null,
                _ => value?.DeepClone(),
            };
        }

        var parent = GetParent(current, segments);
        var finalSegment = segments[^1];

        switch (parent)
        {
            case JsonObject jsonObject:
                ApplyToObject(jsonObject, operation, finalSegment, value);

View on GitHub (pinned to 25830f84bd)