Unity-Technologies/ml-agents · error · TrainerConfigError

Error parsing yaml file. Please check for formatting errors.

Error message

Error parsing yaml file. Please check for formatting errors. A tool such as http://www.yamllint.com/ can be helpful with this.

What it means

_load_config runs yaml.safe_load on the config; a yaml.parser.ParserError (structural YAML syntax problem, not semantic) is converted into a TrainerConfigError suggesting a YAML linter. The message is generic — the original ParserError is chained as __cause__ for details.

Source

Thrown at ml-agents/mlagents/trainers/cli_utils.py:341

            return _load_config(data_file)
    except OSError:
        abs_path = os.path.abspath(config_path)
        raise TrainerConfigError(f"Config file could not be found at {abs_path}.")
    except UnicodeDecodeError:
        raise TrainerConfigError(
            f"There was an error decoding Config file from {config_path}. "
            f"Make sure your file is save using UTF-8"
        )


def _load_config(fp: TextIO) -> Dict[str, Any]:
    """
    Load the yaml config from the file-like object.
    """
    try:
        return yaml.safe_load(fp)
    except yaml.parser.ParserError as e:
        raise TrainerConfigError(
            "Error parsing yaml file. Please check for formatting errors. "
            "A tool such as http://www.yamllint.com/ can be helpful with this."
        ) from e


parser = _create_parser()

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Read the chained ParserError (line/column) in the traceback and fix that YAML line
2. Validate the file at http://www.yamllint.com/ or run yamllint config.yaml
3. Replace tabs with spaces and ensure consistent 2-space indentation
4. Add a space after colons and quote values containing special characters (:)

Example fix

// before
hyperparameters:
	batch_size: 64
   learning_rate:3e-4
// after
hyperparameters:
  batch_size: 64
  learning_rate: 3.0e-4

import yaml
def validate_yaml(path):
    with open(path) as f:
        try:
            yaml.safe_load(f)
        except yaml.parser.ParserError as e:
            raise SystemExit(f"YAML syntax error in {path}: {e}")

try:
    config = load_config(config_path)
except TrainerConfigError as e:
    import yaml
    try:
        yaml.safe_load(open(config_path))
    except yaml.parser.ParserError as pe:
        print(f"Fix YAML at line {pe.problem_mark.line + 1}: {pe.problem}")
    raise

When it happens

Trigger: load_config encountering YAML with broken indentation, tabs instead of spaces, unbalanced quotes/brackets, or a stray 'key: value:' structure. Called from load_config and directly in tests.

Common situations: Hand-editing trainer config YAML and mis-nesting hyperparameters, pasting YAML from a chat/doc losing indentation, using tabs, or forgetting a space after a colon.

Related errors

• There was an error decoding Config file from {config_path}.
• Config doesn't specify a trainer type. Please specify traine
• Config doesn't specify use_recurrent. Please specify true or
• Config file could not be found at {abs_path}.
• The option {key} was specified in your YAML file for {class_

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