Unity-Technologies/ml-agents · error · IndexOutOfRangeException

Index out of bounds, expected a number between 0 and {Length

Error message

Index out of bounds, expected a number between 0 and {Length}

What it means

ActionSegment<T>'s read indexer validates that the index lies between 0 and Length (inclusive upper bound is actually allowed by the check but the message says 'between 0 and Length') before reading Array[Offset + index]. An out-of-range index means the caller is trying to read more actions than the behavior's action space provides. This protects against silently reading another segment's data when Offset indexing goes out of bounds.

Source

Thrown at com.unity.ml-agents/Runtime/Actuators/ActionSegment.cs:88

        /// <summary>
        /// Get the underlying <see cref="Array"/> of this segment.
        /// </summary>
        public T[] Array { get; }

        /// <summary>
        /// Allows access to the underlying array using array syntax.
        /// </summary>
        /// <param name="index">The zero-based index of the segment.</param>
        /// <exception cref="IndexOutOfRangeException">Thrown when the index is less than 0 or
        /// greater than or equal to <see cref="Length"/></exception>
        public T this[int index]
        {
            get
            {
                if (index < 0 || index > Length)
                {
                    throw new IndexOutOfRangeException($"Index out of bounds, expected a number between 0 and {Length}");
                }
                return Array[Offset + index];
            }
            set
            {
                if (index < 0 || index > Length)
                {
                    throw new IndexOutOfRangeException($"Index out of bounds, expected a number between 0 and {Length}");
                }
                Array[Offset + index] = value;
            }
        }

        /// <summary>
        /// Sets the segment of the backing array to all zeros.
        /// </summary>
        public void Clear()
        {

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Update the agent code to use actions.Length or ActionSpec instead of a hardcoded action count
2. Align the Behavior Parameters on the agent prefab with the trainer YAML hyperparameters (action_size / action branches)
3. For hybrid spaces, read the correct segment: ContinuousActions or DiscreteActions, not both

Example fix

// before
var turn = actions[5];
// after
if (actions.Length > 5) { var turn = actions[5]; }

if (index >= 0 && index < actions.Length) {
    var value = actions[index];
}

bool IsValidActionIndex(ActionSegment<float> a, int i) => i >= 0 && i < a.Length;

try { var v = actions[index]; } catch (IndexOutOfRangeException) { /* use default action */ }

When it happens

Trigger: Accessing actions[i] (via an ActionSegment from ActionBuffers.ContinuousActions/DiscreteActions) where i < 0 or i exceeds the segment Length, e.g. reading index 5 of a 3-action continuous segment.

Common situations: Agent action-reaction code hardcoding action counts that no longer match the Behavior Parameters / ActionSpec after editing the number of actions in the trainer config; mismatched branch counts between continuous and discrete settings.

Related errors

• row was {row}, but must be between 0 and {maxBoardSize.Rows
• col was {col}, but must be between 0 and {maxBoardSize.Colum
• Cannot move cell at row={row} col={col} in Direction={dir}
• height value {h} must be in range [0, {m_TensorShape.Height(
• width value {w} must be in range [0, {m_TensorShape.Width()

AI-assisted analysis of Unity-Technologies/ml-agents@3ecb446f75 (2026-09-02). Data as JSON: /api/errors/1cfb754acbce750f. Report an issue: GitHub.