Unity-Technologies/ml-agents · error · BufferException

The length of the fields {key_list} were not of same length

Error message

The length of the fields {key_list} were not of same length

What it means

AgentBuffer.resequence_and_append copies resequenced samples into a target update buffer, but only if all source fields have equal length (rows represent aligned samples). check_length failing raises this BufferException naming the offending key_list.

Source

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

        self,
        target_buffer: "AgentBuffer",
        key_list: List[AgentBufferKey] = None,
        batch_size: int = None,
        training_length: int = None,
    ) -> None:
        """
        Takes in a batch size and training length (sequence length), and appends this AgentBuffer to target_buffer
        properly padded for LSTM use. Optionally, use key_list to restrict which fields are inserted into the new
        buffer.
        :param target_buffer: The buffer which to append the samples to.
        :param key_list: The fields that must be added. If None: all fields will be appended.
        :param batch_size: The number of elements that must be appended. If None: All of them will be.
        :param training_length: The length of the samples that must be appended. If None: only takes one element.
        """
        if key_list is None:
            key_list = list(self.keys())
        if not self.check_length(key_list):
            raise BufferException(
                f"The length of the fields {key_list} were not of same length"
            )
        for field_key in key_list:
            target_buffer[field_key].extend(
                self[field_key].get_batch(
                    batch_size=batch_size, training_length=training_length
                )
            )

    @property
    def num_experiences(self) -> int:
        """
        The number of agent experiences in the AgentBuffer, i.e. the length of the buffer.

        An experience consists of one element across all of the fields of this AgentBuffer.
        Note that these all have to be the same length, otherwise shuffle and append_to_update_buffer
        will fail.
        """

View on GitHub (pinned to 3ecb446f75)

Solutions

  1. Ensure the collection code appends to all fields consistently before each update
  2. Filter key_list down to fields of equal length, or pad/trim fields to match before appending
  3. Compare len(self[k]) for each k in key_list to find the short field and fix its producer

Example fix

// before
buffer.resequence_and_append(target_buffer, training_length=seq_len)  # uneven fields
// after
key_list = list(buffer.keys())
if not buffer.check_length(key_list):
    key_list = [k for k in key_list if len(buffer[k]) == min(len(buffer[k2]) for k2 in key_list)]
buffer.resequence_and_append(target_buffer, training_length=seq_len, key_list=key_list)
Defensive patterns

Strategy: validation

Validate before calling

key_list = key_list or list(buffer.keys())
if not buffer.check_length(key_list):
    lengths = {str(k): len(buffer[k]) for k in key_list}
    raise ValueError(f"Fields not aligned before resequence_and_append: {lengths}")

Try / catch

try:
    buffer.resequence_and_append(target_buffer, training_length=seq_len)
except BufferException as e:
    logger.error(f"Update skipped, misaligned buffer fields: {e}")

Prevention

When it happens

Trigger: Calling resequence_and_append (usually via _append_to_update_buffer / process_batch) when the sample buffer fields have different lengths — e.g. some fields got fewer appends during collection.

Common situations: PPO/SAC training where a policy or reward signal skipped writes for some steps, heterogeneous agent counts per field, or custom trainers appending selectively.

Related errors

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