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.Swap when either of the two items is not found in the array (indexOf returns -1). Swap exchanges the positions of two elements by reference, so both must be members of the same array. The identical-reference shortcut (item1 === item2) returns early without error; only genuinely missing elements throw. Same invariant and message as MoveAbove/MoveBelow.

Source

Thrown at src/utils/array/Swap.js:33

 * @param {array} array - The input array.
 * @param {*} item1 - The first element to swap.
 * @param {*} item2 - The second element to swap.
 *
 * @return {array} The input array.
 */
var Swap = function (array, item1, item2)
{
    if (item1 === item2)
    {
        return array;
    }

    var index1 = array.indexOf(item1);
    var index2 = array.indexOf(item2);

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

    array[index1] = item2;
    array[index2] = item1;

    return array;
};

module.exports = Swap;

View on GitHub (pinned to 41be1e462b)

Solutions

1. Pre-check both: `if (arr.includes(a) && arr.includes(b)) Swap(arr, a, b);`.
2. Operate on references obtained directly from the array (e.g., group.getChildren()[i]) rather than cached copies.
3. If items may be transiently absent, defer the swap until both are confirmed present.
4. For index-based swapping where you know positions, swap via `var t = arr[i]; arr[i] = arr[j]; arr[j] = t;` after bounds-checking i and j.

Example fix

// before
Phaser.Utils.Array.Swap(children, spriteA, spriteB); // spriteB detached

// after
if (children.indexOf(spriteA) !== -1 && children.indexOf(spriteB) !== -1) {
  Phaser.Utils.Array.Swap(children, spriteA, spriteB);
}

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

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

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

When it happens

Trigger: Calling Swap(arr, a, b) where arr.indexOf(a) < 0 or arr.indexOf(b) < 0. Commonly when one element was removed, when a and b come from different arrays, or when comparing objects that are equal by value but not by reference (indexOf uses ===).

Common situations: Swapping z-order of two sprites where one was destroyed between frames. Drag-to-swap UIs where the dragged item is temporarily detached from the list. Using deep-cloned items while swapping against the originals. Race conditions in event-driven reordering where a remove event fires before the swap.

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/c2fdb3aca33a9f37. Report an issue: GitHub.