Unity-Technologies/ml-agents · error · BufferException

The batch size and training length requested for get_batch w

Error message

The batch size and training length requested for get_batch where too large given the current number of data points.

What it means

AgentBuffer.get_batch for non-overlapping sequences (the first branch) computes the maximum batch size as len(self)//training_length plus leftover; requesting more sequences than the buffer can supply without overlap raises BufferException. This also fires when batch_size is None but training_length exceeds the buffer size.

Source

Thrown at ml-agents/mlagents/trainers/buffer.py:172

        None: only takes one element.
        :param sequential: If true and training_length is not None: the elements
        will not repeat in the sequence. [a,b,c,d,e] with training_length = 2 and
        sequential=True gives [[0,a],[b,c],[d,e]]. If sequential=False gives
        [[a,b],[b,c],[c,d],[d,e]]
        """
        if training_length is None:
            training_length = 1
        if sequential:
            # The sequences will not have overlapping elements (this involves padding)
            leftover = len(self) % training_length
            # leftover is the number of elements in the first sequence (this sequence might need 0 padding)
            if batch_size is None:
                # retrieve the maximum number of elements
                batch_size = len(self) // training_length + 1 * (leftover != 0)
            # The maximum number of sequences taken from a list of length len(self) without overlapping
            # with padding is equal to batch_size
            if batch_size > (len(self) // training_length + 1 * (leftover != 0)):
                raise BufferException(
                    "The batch size and training length requested for get_batch where"
                    " too large given the current number of data points."
                )
            if batch_size * training_length > len(self):
                if self.contains_lists:
                    padding = []
                else:
                    # We want to duplicate the last value in the array, multiplied by the padding_value.
                    padding = np.array(self[-1], dtype=np.float32) * self.padding_value
                return self[:] + [padding] * (training_length - leftover)

            else:
                return self[len(self) - batch_size * training_length :]
        else:
            # The sequences will have overlapping elements
            if batch_size is None:
                # retrieve the maximum number of elements
                batch_size = len(self) - training_length + 1

View on GitHub (pinned to 3ecb446f75)

Solutions

Increase trainer hyperparameters that govern how much experience is collected before update (e.g. buffer_size, add more env steps in the buffer).
Lower update_seq_len / sequence_length so it does not exceed len(buffer).
Lower the requested batch_size to at most len(buffer)//training_length.
Advance env.step()/collect more episodes before calling trainer.update.
Check that the buffer was not cleared/never populated (policy behavior output wired correctly).

Example fix

// before
buffer.get_batch(batch_size=1024, training_length=128)  # buffer has 500 points
// after
max_batch = len(buffer) // 128
if max_batch > 0:
    buffer.get_batch(batch_size=min(1024, max_batch), training_length=128)

Defensive patterns

Strategy: validation

Validate before calling

max_batch = len(buffer) // training_length + 1 * (len(buffer) % training_length != 0)
assert batch_size is not None and batch_size <= max_batch and len(buffer) > 0, \
    f"buffer too small: have {len(buffer)} points, need {training_length} seq len"

Try / catch

from mlagents.trainers.exception import BufferException
try:
    batch = buffer.get_batch(batch_size=batch_size, training_length=training_length)
except BufferException:
    batch = None  # collect more experience before updating

Prevention

Check len(buffer) >= training_length before sampling
Cap batch_size at len(buffer)//training_length
Collect enough steps before the first update
Log buffer length and hyperparameters at each update

When it happens

Trigger: policy.update / trainer sampling with update_seq_len (training_length) larger than the number of samples in a policy buffer, or an explicit batch_size above len(buffer)//training_length (+leftover), e.g. requesting batch_size from a nearly empty buffer at the start of training.

Common situations: Training with sequence length 64+ on small buffers; very first update before enough experience accumulates; buffer cleared between updates; batch_size hyperparameter too large for collected experience.

Related errors

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