What causes "No BrainParameters found in demonstration file at {file_path}." in Unity-Technologies/ml-agents?

Re-record the demonstration file in Unity, letting the recording finish and the editor write the complete file.

Unity-Technologies/ml-agents · error · RuntimeError

No BrainParameters found in demonstration file at {file_path

Error message

No BrainParameters found in demonstration file at {file_path}.

What it means

After parsing all records in a .demo file, load_demonstration raises this RuntimeError if no BrainParameters (behavior spec) record was found. A valid demonstration file must contain a brain/behavior parameters section before agent experience records; without it the data cannot be interpreted.

Source

Thrown at ml-agents/mlagents/trainers/demo_loader.py:225

                    pos = INITIAL_POS
                if obs_decoded == 1:
                    brain_param_proto = BrainParametersProto()
                    brain_param_proto.ParseFromString(data[pos : pos + next_pos])
                    pos += next_pos
                if obs_decoded > 1:
                    agent_info_action = AgentInfoActionPairProto()
                    agent_info_action.ParseFromString(data[pos : pos + next_pos])
                    if behavior_spec is None:
                        behavior_spec = behavior_spec_from_proto(
                            brain_param_proto, agent_info_action.agent_info
                        )
                    info_action_pairs.append(agent_info_action)
                    if len(info_action_pairs) == total_expected:
                        break
                    pos += next_pos
                obs_decoded += 1
    if not behavior_spec:
        raise RuntimeError(
            f"No BrainParameters found in demonstration file at {file_path}."
        )
    return behavior_spec, info_action_pairs, total_expected


def write_delimited(f, message):
    msg_string = message.SerializeToString()
    msg_size = len(msg_string)
    _EncodeVarint(f.write, msg_size)
    f.write(msg_string)


def write_demo(demo_path, meta_data_proto, brain_param_proto, agent_info_protos):
    with open(demo_path, "wb") as f:
        # write metadata
        write_delimited(f, meta_data_proto)
        f.seek(INITIAL_POS)
        write_delimited(f, brain_param_proto)

View on GitHub (pinned to 3ecb446f75)

Solutions

Re-record the demonstration file in Unity, letting the recording finish and the editor write the complete file.
Check the file is a genuine .demo recording (non-trivial size, starts with the expected meta header) and re-copy it in binary-safe mode if it was transferred.
Restore the file from version control or a backup if it was corrupted or truncated.

Example fix

// before
demo_path = "demo/demo.demo"  # 0-byte truncated file
// after
demo_path = "demo/demo.demo"  # re-recorded, complete file

Defensive patterns

Strategy: try-catch

Validate before calling

import os
path = "demos/my_demo.demo"
assert os.path.getsize(path) > 33, "demo file too small / truncated (INITIAL_POS header missing)"

Type guard

def looks_like_demo_file(path: str) -> bool:
    import os
    return os.path.isfile(path) and path.endswith(".demo") and os.path.getsize(path) > 33

Try / catch

try:
    demo_spec, pairs, _ = load_demonstration(path)
except RuntimeError as e:
    if "No BrainParameters found" in str(e):
        logger.error("Demo file corrupt/truncated: re-record in Unity")
        raise SystemExit(1)
    raise

Prevention

Let Unity finish writing the demo recording before stopping play mode
Transfer .demo files in binary mode; avoid tools that mangle binary data
Check file size is non-trivial and the recording completed before training

When it happens

Trigger: load_demonstration called on a .demo file that contains no BrainParametersProto section — e.g. a truncated, empty, or corrupt file, or a file whose INITIAL_POS (33-byte) header was stripped or malformed.

Common situations: Recording was interrupted in Unity so the file was never fully written; the file got corrupted in transfer (FTP ASCII mode, git LFS placeholder); someone truncated the header; the path points at a file that isn't actually a demo recording.

Related errors

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