phaserjs/phaser · error · Error

Supplied items must be elements of the same array

Error message

Supplied items must be elements of the same array

What it means

Thrown by Phaser.Utils.Array.MoveBelow when either item1 or item2 is absent from the array (indexOf returns -1). MoveBelow relocates item1 to immediately before item2 (toward the start of the array), so both must be present. Same invariant and same message as MoveAbove/Swap; the guard is identical across these three utilities.

Source

Thrown at src/utils/array/MoveBelow.js:34

 * @param {array} array - The input array.
 * @param {*} item1 - The element to move below the base element.
 * @param {*} item2 - The base element.
 *
 * @return {array} The input array.
 */
var MoveBelow = function (array, item1, item2)
{
    if (item1 === item2)
    {
        return array;
    }

    var currentIndex = array.indexOf(item1);
    var baseIndex = array.indexOf(item2);

    if (currentIndex < 0 || baseIndex < 0)
    {
        throw new Error('Supplied items must be elements of the same array');
    }

    if (currentIndex < baseIndex)
    {
        // item1 is already below item2
        return array;
    }

    //  Remove
    array.splice(currentIndex, 1);

    //  Add in new location
    if (baseIndex === 0)
    {
        array.unshift(item1);
    }
    else
    {

View on GitHub (pinned to 41be1e462b)

Solutions

1. Guard membership first: `if (arr.indexOf(a) !== -1 && arr.indexOf(b) !== -1) MoveBelow(arr, a, b);`.
2. Cache the actual array elements (not look-alikes) before reordering.
3. If the array is a Phaser group's children, use group.getChildren() at call time rather than a cached snapshot.
4. Use MoveTo with an explicit index if you only know the target slot.

Example fix

// before
Phaser.Utils.Array.MoveBelow(list, nodeA, nodeB); // nodeA not in list

// after
var list = group.getChildren();
if (list.indexOf(nodeA) !== -1 && list.indexOf(nodeB) !== -1) {
  Phaser.Utils.Array.MoveBelow(list, nodeA, nodeB);
}

function safeMoveBelow(arr, a, b) {
  if (arr.indexOf(a) !== -1 && arr.indexOf(b) !== -1) {
    return Phaser.Utils.Array.MoveBelow(arr, a, b);
  }
  return arr;
}

function areSameArrayMembers(arr, a, b) {
  return arr.indexOf(a) !== -1 && arr.indexOf(b) !== -1;
}

try {
  Phaser.Utils.Array.MoveBelow(arr, a, b);
} catch (e) {
  if (e.message !== 'Supplied items must be elements of the same array') throw e;
  // graceful no-op
}

When it happens

Trigger: Calling MoveBelow(arr, a, b) with arr.indexOf(a) < 0 or arr.indexOf(b) < 0. Same family of causes as MoveAbove: stale references, value-vs-reference mismatches, items removed by a prior operation, or items belonging to a different array instance.

Common situations: Reordering z-order in a container or group where a child was destroyed between frames. Drag-and-drop reordering where the drop target was unmounted. Comparing Phaser Game Objects by a deep-equal helper while indexOf uses reference equality. Async scene transitions that null out references.

Related errors

• Supplied items must be elements of the same array
• Supplied items must be elements of the same array
• Supplied index out of bounds
• Index out of bounds
• Range Error: Values outside acceptable range

AI-assisted analysis of phaserjs/phaser@41be1e462b (2026-08-13). Data as JSON: /api/errors/3d288784ece3ec60. Report an issue: GitHub.