{"record":{"id":"cd784b9d507cd501","repo":"OrchardCMS/OrchardCore","slug":"unexpected-merge-array-handling-when-merging-json","errorCode":null,"errorMessage":"Unexpected merge array handling when merging JSON.","messagePattern":"Unexpected merge array handling when merging JSON\\.","errorType":"exception","errorClass":"ArgumentOutOfRangeException","httpStatus":null,"severity":"error","filePath":"src/OrchardCore/OrchardCore.Abstractions/Json/Nodes/JArray.cs","lineNumber":210,"sourceCode":"                        if (existingItem is JsonValue || existingItem.GetValueKind() != item.GetValueKind())\n                        {\n                            if (item.GetValueKind() != JsonValueKind.Null ||\n                                settings?.MergeNullValueHandling == MergeNullValueHandling.Merge)\n                            {\n                                jsonArray[i] = item.Clone();\n                            }\n                        }\n                    }\n                    else\n                    {\n                        jsonArray.Add(item.Clone());\n                    }\n                }\n\n                break;\n\n            default:\n                throw new ArgumentOutOfRangeException(nameof(settings), \"Unexpected merge array handling when merging JSON.\");\n        }\n\n        return jsonArray;\n    }\n}\n","sourceCodeStart":192,"sourceCodeEnd":216,"githubUrl":"https://github.com/OrchardCMS/OrchardCore/blob/4306c0717fe573f6fca1b4955909ddab6a192807/src/OrchardCore/OrchardCore.Abstractions/Json/Nodes/JArray.cs#L192-L216","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Validate the MergeArrayHandling value is defined with Enum.IsDefined before merging","Explicitly set MergeArrayHandling to a valid member (Concat, Union, Replace, Ignore)","Fix the source of the corrupted/invalid settings value","Default invalid values to MergeArrayHandling.Concat before calling Merge"],"exampleFix":"// before\narray.Merge(other, new JsonMergeSettings { MergeArrayHandling = (MergeArrayHandling)raw });\n// after\nvar handling = Enum.IsDefined(typeof(MergeArrayHandling), raw) ? (MergeArrayHandling)raw : MergeArrayHandling.Concat;\narray.Merge(other, new JsonMergeSettings { MergeArrayHandling = handling });","handlingStrategy":"validation","validationCode":"if (!Enum.IsDefined(settings.MergeArrayHandling))\n    throw new ArgumentException($\"Invalid MergeArrayHandling value: {settings.MergeArrayHandling}\");","typeGuard":null,"tryCatchPattern":"try { array.Merge(other, settings); }\ncatch (ArgumentOutOfRangeException ex) { /* log ex, retry with default */\n    array.Merge(other, new JsonMergeSettings { MergeArrayHandling = MergeArrayHandling.Concat }); }","preventionTips":["Only assign defined MergeArrayHandling enum members","Never cast raw ints from config/db into MergeArrayHandling without Enum.IsDefined","Default unknown persisted enum values to Concat before merging","Validate settings deserialized from external sources"],"tags":["argument-out-of-range","json","merge","enum"],"backgroundTag":"invalid-enum-value","analyzedSha":"4306c0717fe573f6fca1b4955909ddab6a192807","analyzedAt":"2026-09-13T17:41:05.024Z","contentChangedAt":"2026-09-13T17:41:05.024Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}