OrchardCMS/OrchardCore · error · ArgumentOutOfRangeException

Unexpected merge array handling when merging JSON.

Error message

Unexpected merge array handling when merging JSON.

What it means

This ArgumentOutOfRangeException is thrown by JArray.Merge when the MergeArrayHandling value in the merge settings is not one of the defined enum members. It is a defensive default branch that should only be hit with an invalid or out-of-range cast enum value.

Solutions

1. Validate the MergeArrayHandling value is defined with Enum.IsDefined before merging
2. Explicitly set MergeArrayHandling to a valid member (Concat, Union, Replace, Ignore)
3. Fix the source of the corrupted/invalid settings value
4. Default invalid values to MergeArrayHandling.Concat before calling Merge

Example fix

// before
array.Merge(other, new JsonMergeSettings { MergeArrayHandling = (MergeArrayHandling)raw });
// after
var handling = Enum.IsDefined(typeof(MergeArrayHandling), raw) ? (MergeArrayHandling)raw : MergeArrayHandling.Concat;
array.Merge(other, new JsonMergeSettings { MergeArrayHandling = handling });

if (!Enum.IsDefined(settings.MergeArrayHandling))
    throw new ArgumentException($"Invalid MergeArrayHandling value: {settings.MergeArrayHandling}");

try { array.Merge(other, settings); }
catch (ArgumentOutOfRangeException ex) { /* log ex, retry with default */
    array.Merge(other, new JsonMergeSettings { MergeArrayHandling = MergeArrayHandling.Concat }); }

When it happens

Trigger: Calling JArray.Merge (or JsonNode merge APIs) with MergeArrayHandling settings containing an undefined value, e.g. (MergeArrayHandling)999 from a cast, bad deserialization, or an out-of-range persisted config.

Common situations: Merge settings loaded from config/database as raw integers and cast unchecked; newer enum value written by a newer library version then read by an older one.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• The calendar is not supported.
• Cannot convert to
• Cannot convert to Boolean
• Cannot convert to Byte
• Cannot convert to Char

AI-assisted analysis of OrchardCMS/OrchardCore@4306c0717f (2026-09-13). Data as JSON: /api/errors/cd784b9d507cd501. Report an issue: GitHub.

Appendix: source

Thrown at src/OrchardCore/OrchardCore.Abstractions/Json/Nodes/JArray.cs:210

                        if (existingItem is JsonValue || existingItem.GetValueKind() != item.GetValueKind())
                        {
                            if (item.GetValueKind() != JsonValueKind.Null ||
                                settings?.MergeNullValueHandling == MergeNullValueHandling.Merge)
                            {
                                jsonArray[i] = item.Clone();
                            }
                        }
                    }
                    else
                    {
                        jsonArray.Add(item.Clone());
                    }
                }

                break;

            default:
                throw new ArgumentOutOfRangeException(nameof(settings), "Unexpected merge array handling when merging JSON.");
        }

        return jsonArray;
    }
}

View on GitHub (pinned to 4306c0717f)