phaserjs/phaser · error · Error

Supplied index out of bounds

Error message

Supplied index out of bounds

What it means

Thrown by Phaser.Utils.Array.MoveTo when the item is not in the array (indexOf === -1) OR the target index is outside [0, array.length-1]. Note the message ('Supplied index out of bounds') is shared by two distinct failure modes: a missing item and an out-of-range target index. MoveTo relocates an element to an absolute index via two splices, so both the source position and the destination must be valid.

Source

Thrown at src/utils/array/MoveTo.js:26

 * Moves an element in an array to a new position within the same array.
 * The array is modified in-place.
 *
 * @function Phaser.Utils.Array.MoveTo
 * @since 3.4.0
 *
 * @param {array} array - The array.
 * @param {*} item - The element to move.
 * @param {number} index - The new index that the element will be moved to.
 *
 * @return {*} The element that was moved.
 */
var MoveTo = function (array, item, index)
{
    var currentIndex = array.indexOf(item);

    if (currentIndex === -1 || index < 0 || index >= array.length)
    {
        throw new Error('Supplied index out of bounds');
    }

    if (currentIndex !== index)
    {
        //  Remove
        array.splice(currentIndex, 1);

        //  Add in new location
        array.splice(index, 0, item);
    }

    return item;
};

module.exports = MoveTo;

View on GitHub (pinned to 41be1e462b)

Solutions

1. Clamp the target index: `idx = Phaser.Math.Clamp(idx, 0, arr.length - 1)` before calling.
2. Verify the item is present: `if (arr.indexOf(item) === -1) return;`.
3. For appending to the end, use arr.push after removing the item, rather than MoveTo with index === length.
4. Handle empty arrays explicitly before computing an index.

Example fix

// before
Phaser.Utils.Array.MoveTo(arr, item, arr.length); // arr.length is out of bounds

// after
var idx = Phaser.Math.Clamp(targetIndex, 0, arr.length - 1);
if (arr.indexOf(item) !== -1) {
  Phaser.Utils.Array.MoveTo(arr, item, idx);
}

function safeMoveTo(arr, item, index) {
  if (arr.indexOf(item) === -1) return item;
  if (arr.length === 0) return item;
  var idx = Phaser.Math.Clamp(index, 0, arr.length - 1);
  return Phaser.Utils.Array.MoveTo(arr, item, idx);
}

function isValidMoveTo(arr, item, index) {
  return arr.indexOf(item) !== -1 && index >= 0 && index < arr.length;
}

try {
  Phaser.Utils.Array.MoveTo(arr, item, targetIndex);
} catch (e) {
  if (e.message === 'Supplied index out of bounds') {
    var idx = Phaser.Math.Clamp(targetIndex, 0, Math.max(0, arr.length - 1));
    if (arr.indexOf(item) !== -1) Phaser.Utils.Array.MoveTo(arr, item, idx);
  } else { throw e; }
}

When it happens

Trigger: Calling MoveTo(arr, item, index) where item is not present, or index < 0, or index >= arr.length. Edge case: calling on an empty array (length 0) makes any index out of bounds. Edge case: index === arr.length is rejected even though splice technically tolerates it, because the guard uses >=.

Common situations: Computing the target index from UI state that can exceed the list length after a deletion. Off-by-one when moving to the end (using arr.length instead of arr.length - 1). Calling MoveTo on an item that was just removed in the same handler. Passing a fractional or NaN index (NaN fails the < 0 check is false but NaN >= length is also false, so NaN slips through unless length is 0; the splice then behaves unexpectedly, but a non-integer index still violates intent).

Related errors

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

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