{"record":{"id":"f2243f510cc8ce65","repo":"Unity-Technologies/ml-agents","slug":"unable-to-shuffle-if-the-fields-are-not-of-same-le","errorCode":null,"errorMessage":"Unable to shuffle if the fields are not of same length","messagePattern":"Unable to shuffle if the fields are not of same length","errorType":"exception","errorClass":"BufferException","httpStatus":null,"severity":"error","filePath":"ml-agents/mlagents/trainers/buffer.py","lineNumber":394,"sourceCode":"            if key not in self._fields:\n                return False\n            if (length is not None) and (length != len(self[key])):\n                return False\n            length = len(self[key])\n        return True\n\n    def shuffle(\n        self, sequence_length: int, key_list: List[AgentBufferKey] = None\n    ) -> None:\n        \"\"\"\n        Shuffles the fields in key_list in a consistent way: The reordering will\n        be the same across fields.\n        :param key_list: The fields that must be shuffled.\n        \"\"\"\n        if key_list is None:\n            key_list = list(self._fields.keys())\n        if not self.check_length(key_list):\n            raise BufferException(\n                \"Unable to shuffle if the fields are not of same length\"\n            )\n        s = np.arange(len(self[key_list[0]]) // sequence_length)\n        np.random.shuffle(s)\n        for key in key_list:\n            buffer_field = self[key]\n            tmp: List[np.ndarray] = []\n            for i in s:\n                tmp += buffer_field[i * sequence_length : (i + 1) * sequence_length]\n            buffer_field.set(tmp)\n\n    def make_mini_batch(self, start: int, end: int) -> \"AgentBuffer\":\n        \"\"\"\n        Creates a mini-batch from buffer.\n        :param start: Starting index of buffer.\n        :param end: Ending index of buffer.\n        :return: Dict of mini batch.\n        \"\"\"","sourceCodeStart":376,"sourceCodeEnd":412,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents/mlagents/trainers/buffer.py#L376-L412","documentation":"AgentBuffer.shuffle randomly permutes whole sequences across the requested fields; this only makes sense if all fields have the same number of elements so rows stay aligned. check_length detects a mismatch and raises BufferException.","triggerScenarios":"Calling buffer.shuffle(sequence_length, key_list) where one of the fields was appended fewer/more times than the others (e.g. missing reward fields for some agents, or a partial update_batch).","commonSituations":"Training with multiple reward signals where one signal produced no entries, custom experience-collection code appending to only some buffer fields, or off-by-one sequence_length handling.","solutions":["Check that every key in key_list exists and has identical length before shuffling: buffer.check_length(key_list)","Verify all experience-collection code appends to every field on every step","Rebuild the buffer from a complete episode set, dropping fields with missing entries"],"exampleFix":"// before\nbuffer.shuffle(sequence_length)  # fields unequal\n// after\nkey_list = [k for k in buffer.keys() if len(buffer[k]) == buffer[buffer.keys()[0]].length]\nassert buffer.check_length(key_list)\nbuffer.shuffle(sequence_length, key_list)","handlingStrategy":"validation","validationCode":"key_list = key_list or list(buffer._fields.keys())\nlengths = {k: len(buffer[k]) for k in key_list}\nif len(set(lengths.values())) != 1:\n    raise ValueError(f\"Unequal field lengths before shuffle: {lengths}\")\nbuffer.shuffle(sequence_length, key_list)","typeGuard":null,"tryCatchPattern":"try:\n    buffer.shuffle(sequence_length, key_list)\nexcept BufferException:\n    key_list = [k for k in key_list if len(buffer[k]) == min(len(buffer[j]) for j in key_list)]\n    buffer.shuffle(sequence_length, key_list)","preventionTips":["Call buffer.check_length(key_list) yourself before any shuffle/update operation","Make every experience-collection append write to ALL buffer fields","Track field lengths when adding custom reward/policy fields to the buffer"],"tags":["bufferexception","ml-agents","buffer","data-integrity"],"backgroundTag":"buffer-field-length-mismatch","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}