{"record":{"id":"313fa8a840246580","repo":"roboflow/supervision","slug":"unexpected-array-dimension-for-key-key","errorCode":null,"errorMessage":"Unexpected array dimension for key '{key}'.","messagePattern":"Unexpected array dimension for key '(.+?)'\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/detection/utils/internal.py","lineNumber":589,"sourceCode":"                \"All data values within a single object must have equal length.\"\n            )\n\n    merged_data: dict[str, Any] = {key: [] for key in all_keys_sets[0]}\n    for data in data_list:\n        for key in data:\n            merged_data[key].append(data[key])\n\n    for key in merged_data:\n        if all(isinstance(item, list) for item in merged_data[key]):\n            merged_data[key] = list(chain.from_iterable(merged_data[key]))\n        elif all(isinstance(item, np.ndarray) for item in merged_data[key]):\n            ndim = merged_data[key][0].ndim\n            if ndim == 1:\n                merged_data[key] = np.hstack(merged_data[key])\n            elif ndim > 1:\n                merged_data[key] = np.vstack(merged_data[key])\n            else:\n                raise ValueError(f\"Unexpected array dimension for key '{key}'.\")\n        else:\n            raise ValueError(\n                f\"Inconsistent data types for key '{key}'. Only np.ndarray and list \"\n                f\"types are allowed.\"\n            )\n\n    return cast(_DetectionDataType, merged_data)\n\n\ndef merge_metadata(metadata_list: list[_MetadataType]) -> _MetadataType:\n    \"\"\"\n    Merge metadata from a list of metadata dictionaries.\n\n    This function combines the metadata dictionaries. If a key appears in more than one\n    dictionary, the values must be identical for the merge to succeed.\n\n    Warning: Assumes that empty detections were filtered-out before passing metadata to\n    this function.","sourceCodeStart":571,"sourceCodeEnd":607,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/detection/utils/internal.py#L571-L607","documentation":"Raised by merge_data when a data value is an np.ndarray with ndim == 0 (a scalar array). The merge logic only defines hstack for 1-D and vstack for n-D arrays; a 0-d array fits neither, so it is rejected as an unexpected dimension.","triggerScenarios":"sv.Detections.merge([d1, ...]) where some input's data value is np.asarray(scalar), e.g. d.data['frame_id'] = np.asarray(42) or np.float64(0.5). Such a value is also misaligned with xyxy (one scalar for N detections) and would fail length checks first if N > 1.","commonSituations":"Wrapping scalar per-object values with np.asarray when populating data, producing 0-d arrays; storing np.float64/np.int64 scalars (which are 0-d array-likes) in data; migrating a metadata-style value into data without reshaping to per-detection shape.","solutions":["Store per-detection values as 1-D arrays: np.full(len(detections), 42) or np.asarray([42]*len(detections))","Move true per-object scalars into Detections.metadata instead of data","Validate ndim >= 1 and length == len(xyxy) for every data value before merge"],"exampleFix":"# before\nd.data['frame_id'] = np.asarray(42)  # 0-d\nmerged = sv.Detections.merge([d, other])\n# after\nd.data['frame_id'] = np.full(len(d), 42)  # 1-D, aligned\nmerged = sv.Detections.merge([d, other])","handlingStrategy":"validation","validationCode":"import numpy as np\n\ndef assert_data_shapes_mergeable(detections_list):\n    for d in detections_list:\n        n = len(d.xyxy)\n        for k, v in d.data.items():\n            arr = np.asarray(v)\n            assert arr.ndim >= 1 and len(arr) == n, f\"data['{k}'] bad shape {arr.shape} for {n} detections\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Build data values with np.full(len(d), value), never np.asarray(scalar)","Keep per-object scalars in Detections.metadata","Check arr.ndim >= 1 when wrapping external values into detections.data"],"tags":["detections","data-dict","merge","numpy"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}