What causes "Unexpected merge array handling when merging JSON." in JamesNK/Newtonsoft.Json?

Validate the enum before merging: Enum.IsDefined(typeof(MergeArrayHandling), value) and reject/fallback if false.

JamesNK/Newtonsoft.Json · error · ArgumentOutOfRangeException

Unexpected merge array handling when merging JSON.

Error message

Unexpected merge array handling when merging JSON.

What it means

ArgumentOutOfRangeException thrown by JContainer.MergeEnumerableContent when the MergeArrayHandling value is not one of the defined enum members (Concat, Union, Replace, Merge). The switch over the enum falls through to default; this is only reachable when an undefined/corrupted enum value is supplied, since all four defined members are handled.

Source

Thrown at Src/Newtonsoft.Json/Linq/JContainer.cs:1270

                                {
                                    JToken contentValue = CreateFromContent(targetItem);
                                    if (contentValue.Type != JTokenType.Null)
                                    {
                                        target[i] = contentValue;
                                    }
                                }
                            }
                        }
                        else
                        {
                            target.Add(CreateFromContent(targetItem));
                        }

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

View on GitHub (pinned to 4f73e74372)

Solutions

Validate the enum before merging: Enum.IsDefined(typeof(MergeArrayHandling), value) and reject/fallback if false.
Use only named MergeArrayHandling members (Concat/Union/Replace/Merge) from strongly-typed config.
If accepting user-supplied values, parse with Enum.Parse (case-sensitive) or map known strings explicitly.

Example fix

// before
var settings = new JsonMergeSettings { MergeArrayHandling = (MergeArrayHandling)42 };
targetArray.Merge(sourceArray, settings);

// after
MergeArrayHandling h;
var ok = Enum.TryParse<MergeArrayHandling>(userValue, true, out h) && Enum.IsDefined(typeof(MergeArrayHandling), h);
var settings = new JsonMergeSettings { MergeArrayHandling = ok ? h : MergeArrayHandling.Concat };

Defensive patterns

Strategy: validation

Validate before calling

if (!Enum.IsDefined(typeof(MergeArrayHandling), settings.MergeArrayHandling))
{
    throw new ArgumentOutOfRangeException(nameof(settings), "Invalid MergeArrayHandling.");
}

Type guard

static bool IsValid(MergeArrayHandling h) => Enum.IsDefined(typeof(MergeArrayHandling), h);

Try / catch

try { target.Merge(source, settings); }
catch (ArgumentOutOfRangeException ex) when (ex.Message.Contains("merge array handling"))
{
    settings.MergeArrayHandling = MergeArrayHandling.Concat;
    target.Merge(source, settings);
}

Prevention

Always construct MergeArrayHandling from named enum members.
Validate user-supplied enum values with Enum.IsDefined before merging.
Avoid casting arbitrary integers to MergeArrayHandling.

When it happens

Trigger: Passing a JsonMergeSettings with MergeArrayHandling set to an undefined enum value, e.g. (MergeArrayHandling)999, to JContainer.Merge when merging arrays. Reachable via reflection, unsafe enum casts, or a corrupted/instantiated-with-invalid-int enum.

Common situations: Casting an arbitrary integer to MergeArrayHandling; deserializing a MergeArrayHandling from untrusted/loosely-typed config without validation; reflection-driven code that sets the property via a boxed enum.

Related errors

AI-assisted analysis of JamesNK/Newtonsoft.Json@4f73e74372 (2026-08-07). Data as JSON: /api/errors/dd6762d7c3061185. Report an issue: GitHub.