{"record":{"id":"c1a7c9ec2dd8910f","repo":"phaserjs/phaser","slug":"supplied-items-must-be-elements-of-the-same-array","errorCode":null,"errorMessage":"Supplied items must be elements of the same array","messagePattern":"Supplied items must be elements of the same array","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/utils/array/MoveAbove.js","lineNumber":34,"sourceCode":" * @param {array} array - The input array.\n * @param {*} item1 - The element to move above the base element.\n * @param {*} item2 - The base element.\n *\n * @return {array} The input array.\n */\nvar MoveAbove = function (array, item1, item2)\n{\n    if (item1 === item2)\n    {\n        return array;\n    }\n\n    var currentIndex = array.indexOf(item1);\n    var baseIndex = array.indexOf(item2);\n\n    if (currentIndex < 0 || baseIndex < 0)\n    {\n        throw new Error('Supplied items must be elements of the same array');\n    }\n\n    if (currentIndex > baseIndex)\n    {\n        // item1 is already above item2\n        return array;\n    }\n\n    // Remove item1 from its current position\n    array.splice(currentIndex, 1);\n\n    // Recalculate baseIndex after removal\n    baseIndex = array.indexOf(item2);\n\n    // Insert item1 immediately after item2\n    array.splice(baseIndex + 1, 0, item1);\n    \n    return array;","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/phaserjs/phaser/blob/41be1e462bc600064e498cba370bfa8c5c055a22/src/utils/array/MoveAbove.js#L16-L52","documentation":"Thrown by Phaser.Utils.Array.MoveAbove when either item1 or item2 is not present in the supplied array (indexOf returns -1). MoveAbove relocates item1 to immediately after item2 (toward the end of the array), so both must be members of the same array. The guard runs after the identical-reference shortcut, so passing the same object twice is allowed; only genuinely missing elements throw.","triggerScenarios":"Calling MoveAbove(arr, a, b) where arr.indexOf(a) === -1 or arr.indexOf(b) === -1. Commonly when one item was already spliced out, when comparing value-types that look equal but are different references (indexOf uses ===), or when passing an item from a sibling array by mistake.","commonSituations":"Reordering a display list or children array after a remove operation moved an element. Using MoveAbove on a copy of an array while the items reference the original. Comparing objects by value when indexOf compares by reference. Race between an async removal and the MoveAbove call. Using primitive duplicates (two separate strings/numbers with the same value works by === but two separate objects with equal shape do not).","solutions":["Verify membership before calling: `if (arr.includes(a) && arr.includes(b)) MoveAbove(arr, a, b);`.","Ensure both items are the exact same object references that were pushed into the array (not equivalent copies).","If items may have been removed, re-fetch them from the array before reordering.","Consider Phaser.Utils.Array.MoveTo(arr, item, newIndex) if you only know the target position."],"exampleFix":"// before\nPhaser.Utils.Array.MoveAbove(children, spriteA, spriteB); // spriteB already removed\n\n// after\nif (children.includes(spriteA) && children.includes(spriteB)) {\n  Phaser.Utils.Array.MoveAbove(children, spriteA, spriteB);\n}","handlingStrategy":"validation","validationCode":"function safeMoveAbove(arr, a, b) {\n  if (arr.indexOf(a) !== -1 && arr.indexOf(b) !== -1) {\n    return Phaser.Utils.Array.MoveAbove(arr, a, b);\n  }\n  return arr;\n}","typeGuard":"function areSameArrayMembers(arr, a, b) {\n  return arr.indexOf(a) !== -1 && arr.indexOf(b) !== -1;\n}","tryCatchPattern":"try {\n  Phaser.Utils.Array.MoveAbove(arr, a, b);\n} catch (e) {\n  if (e.message !== 'Supplied items must be elements of the same array') throw e;\n  // graceful no-op: one item is no longer present\n}","preventionTips":["Always use the exact object references stored in the array, not equivalent copies.","Refresh the array reference (e.g. group.getChildren()) right before reordering.","Skip reordering when a removal happens in the same frame.","Wrap MoveAbove in a membership check helper in your codebase."],"tags":["array","reorder","membership","indexof","utils"],"backgroundTag":null,"analyzedSha":"41be1e462bc600064e498cba370bfa8c5c055a22","analyzedAt":"2026-08-13T04:23:39.729Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}