Unity-Technologies/ml-agents · error · ValueError

Unable to convert {encoded_key} to an AgentBufferKey

Error message

Unable to convert {encoded_key} to an AgentBufferKey

What it means

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.

Source

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

        try:
            return BufferKey(encoded_key)
        except ValueError:
            pass

        # Not a simple key, so split into two parts
        prefix_str, _, suffix_str = encoded_key.partition(":")

        # See if it's an ObservationKeyPrefix first
        try:
            return ObservationKeyPrefix(prefix_str), int(suffix_str)
        except ValueError:
            pass

        # If not, it had better be a RewardSignalKeyPrefix
        try:
            return RewardSignalKeyPrefix(prefix_str), suffix_str
        except ValueError:
            raise ValueError(f"Unable to convert {encoded_key} to an AgentBufferKey")

    def __getitem__(self, key: AgentBufferKey) -> AgentBufferField:
        if self.CHECK_KEY_TYPES_AT_RUNTIME:
            self._check_key(key)
        return self._fields[key]

    def __setitem__(self, key: AgentBufferKey, value: AgentBufferField) -> None:
        if self.CHECK_KEY_TYPES_AT_RUNTIME:
            self._check_key(key)
        self._fields[key] = value

    def __delitem__(self, key: AgentBufferKey) -> None:
        if self.CHECK_KEY_TYPES_AT_RUNTIME:
            self._check_key(key)
        self._fields.__delitem__(key)

    def __iter__(self):
        return self._fields.__iter__()

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Regenerate the buffer file with the same ml-agents version you are loading it with
2. Inspect the offending encoded_key string and fix it to a valid prefix (observation name or reward signal name)
3. Fall back to rebuilding the buffer from raw demonstration/experience data instead of loading the file

from mlagents.trainers.buffer import AgentBuffer
try:
    key = AgentBuffer._decode_key(encoded_key)
except ValueError as e:
    logger.error(f"Skipping unusable key: {e}")
    key = None

try:
    buffer = AgentBuffer.load_from_file(path)
except ValueError as e:
    if 'Unable to convert' in str(e):
        logger.error(f"Buffer file {path} has incompatible keys: {e}")
        buffer = None

When it happens

Trigger: 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.

Common situations: Loading experience/buffer dumps produced by another trainer version, manually renaming fields inside a saved buffer file, or corrupted serialization.

Related errors

• {key} has type ({type(key0)}, {type(key1)})
• {key} is a {type(key)}
• Unable to shuffle if the fields are not of same length
• The length of the fields {key_list} were not of same length
• The path provided is not a '.demo' file.

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