{"record":{"id":"14f898fed51051a6","repo":"Unity-Technologies/ml-agents","slug":"unable-to-convert-encoded-key-to-an-agentbufferk","errorCode":null,"errorMessage":"Unable to convert {encoded_key} to an AgentBufferKey","messagePattern":"Unable to convert (.+?) to an AgentBufferKey","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"ml-agents/mlagents/trainers/buffer.py","lineNumber":333,"sourceCode":"        try:\n            return BufferKey(encoded_key)\n        except ValueError:\n            pass\n\n        # Not a simple key, so split into two parts\n        prefix_str, _, suffix_str = encoded_key.partition(\":\")\n\n        # See if it's an ObservationKeyPrefix first\n        try:\n            return ObservationKeyPrefix(prefix_str), int(suffix_str)\n        except ValueError:\n            pass\n\n        # If not, it had better be a RewardSignalKeyPrefix\n        try:\n            return RewardSignalKeyPrefix(prefix_str), suffix_str\n        except ValueError:\n            raise ValueError(f\"Unable to convert {encoded_key} to an AgentBufferKey\")\n\n    def __getitem__(self, key: AgentBufferKey) -> AgentBufferField:\n        if self.CHECK_KEY_TYPES_AT_RUNTIME:\n            self._check_key(key)\n        return self._fields[key]\n\n    def __setitem__(self, key: AgentBufferKey, value: AgentBufferField) -> None:\n        if self.CHECK_KEY_TYPES_AT_RUNTIME:\n            self._check_key(key)\n        self._fields[key] = value\n\n    def __delitem__(self, key: AgentBufferKey) -> None:\n        if self.CHECK_KEY_TYPES_AT_RUNTIME:\n            self._check_key(key)\n        self._fields.__delitem__(key)\n\n    def __iter__(self):\n        return self._fields.__iter__()","sourceCodeStart":315,"sourceCodeEnd":351,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents/mlagents/trainers/buffer.py#L315-L351","documentation":"AgentBuffer._decode_key converts an encoded string key back into an AgentBufferKey tuple. After trying ObservationKeyPrefix and RewardSignalKeyPrefix, if neither constructor accepts the prefix, a ValueError is raised saying the string cannot be converted.","triggerScenarios":"Calling AgentBuffer.load_from_file on a file whose keys were encoded by a different ml-agents version or hand-edited, so the prefix part before the delimiter matches no known key prefix class.","commonSituations":"Loading experience/buffer dumps produced by another trainer version, manually renaming fields inside a saved buffer file, or corrupted serialization.","solutions":["Regenerate the buffer file with the same ml-agents version you are loading it with","Inspect the offending encoded_key string and fix it to a valid prefix (observation name or reward signal name)","Fall back to rebuilding the buffer from raw demonstration/experience data instead of loading the file"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"from mlagents.trainers.buffer import AgentBuffer\ntry:\n    key = AgentBuffer._decode_key(encoded_key)\nexcept ValueError as e:\n    logger.error(f\"Skipping unusable key: {e}\")\n    key = None","typeGuard":null,"tryCatchPattern":"try:\n    buffer = AgentBuffer.load_from_file(path)\nexcept ValueError as e:\n    if 'Unable to convert' in str(e):\n        logger.error(f\"Buffer file {path} has incompatible keys: {e}\")\n        buffer = None","preventionTips":["Save and load buffer files with the same ml-agents version","Never hand-edit keys inside serialized buffer files","Test-decode keys (_decode_key) before trusting a buffer dump"],"tags":["valueerror","deserialization","ml-agents","buffer"],"backgroundTag":"key-deserialization-failed","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}