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.

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
• Range Error: Values outside acceptable range
• Supplied items must be elements of the same array
• Supplied items must be elements of the same array
• 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.

Appendix: 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)