{"record":{"id":"6b75debfab8b0208","repo":"roboflow/supervision","slug":"expected-mapping-in-data-yaml-at-file-path-go","errorCode":null,"errorMessage":"Expected mapping in data.yaml at '{file_path}', got {type(data).__name__}.","messagePattern":"Expected mapping in data\\.yaml at '(.+?)', got (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/dataset/formats/yolo.py","lineNumber":99,"sourceCode":"    all int-like (plain ints or digit strings) are sorted numerically so\n    class index 10 follows index 9. All-non-numeric keys are sorted\n    lexicographically. Mixed numeric/non-numeric keys raise ``ValueError``.\n    Boolean YAML keys (``true``/``false``) are excluded from numeric sorting\n    because ``bool`` is a subclass of ``int`` in Python.\n\n    Args:\n        file_path: Path to the data.yaml file.\n\n    Returns:\n        Class names in class-index order.\n\n    Raises:\n        ValueError: If the YAML root is not a mapping, if ``names`` is\n            neither a list nor a dict, or if the dict has mixed key types.\n    \"\"\"\n    data: dict[str, Any] = read_yaml_file(file_path=file_path)\n    if not isinstance(data, dict):\n        raise ValueError(\n            f\"Expected mapping in data.yaml at '{file_path}',\"\n            f\" got {type(data).__name__}.\"\n        )\n    names = data.get(\"names\")\n    if isinstance(names, dict):\n        keys = list(names.keys())\n\n        def _is_int_like(key: Any) -> bool:\n            # bool subclasses int; YAML `true`/`false` must not become class indices\n            if isinstance(key, bool):\n                return False\n            if isinstance(key, int):\n                return True\n            if isinstance(key, str):\n                stripped = key.strip()\n                return stripped.isdigit()\n            return False\n","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/dataset/formats/yolo.py#L81-L117","documentation":"Raised when the parsed YAML root of data.yaml is not a mapping (dict). The loader does data.get('names'), so the root must be a key/value mapping; a YAML file whose top level is a list, a scalar, or null cannot contain a names entry, and the error reports the offending root type.","triggerScenarios":"DetectionDataset.from_yolo(data_yaml_path=...) where the yaml file's top-level structure is a sequence (leading '- ' items), a bare scalar, or empty/null — e.g. pointing data_yaml_path at a YOLO labels .txt (names file) instead of data.yaml, or at an empty file.","commonSituations":"Passing the old-style `names.txt` or a normalized .yaml misparsed as a list; truncated/empty data.yaml; wrong file passed via data_yaml_path; yaml produced by a tool that emits a top-level array.","solutions":["Verify data_yaml_path points at the dataset's data.yaml, not names.txt or a labels file.","Check the top of the file: entries like `path:`, `train:`, `names:` at column 0 indicate a mapping root.","If the root is a list or scalar, restructure the file to a mapping with a names key.","Quick sanity check: python -c \"import yaml; print(type(yaml.safe_load(open('data.yaml'))))\" should print dict."],"exampleFix":"# before (root is a sequence)\n- person\n- car\n# after (root is a mapping)\npath: ./dataset\ntrain: images/train\nnames:\n  - person\n  - car","handlingStrategy":"type-guard","validationCode":"import yaml\n\ndef is_mapping_yaml(path: str) -> bool:\n    \"\"\"Check that a YAML file's root is a mapping (dict).\"\"\"\n    with open(path) as f:\n        return isinstance(yaml.safe_load(f), dict)","typeGuard":"def is_mapping(data: object) -> bool:\n    \"\"\"True when the parsed YAML root is a dict.\"\"\"\n    return isinstance(data, dict)","tryCatchPattern":"try:\n    dataset = sv.DetectionDataset.from_yolo(data_yaml_path='data.yaml')\nexcept ValueError as e:\n    if 'Expected mapping in data.yaml' in str(e):\n        raise SystemExit(f'{\"data.yaml\"} root is not a mapping: {e}') from e\n    raise","preventionTips":["Point data_yaml_path at the dataset's data.yaml, never names.txt or label files.","Top-level keys of data.yaml should be path/train/val/names — no leading dashes.","Sanity-check with yaml.safe_load before loading large datasets."],"tags":["yolo","dataset","yaml","config"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}