{"record":{"id":"4f0fd4f446fe47b8","repo":"pola-rs/polars","slug":"read-an-array-from-a-non-array-data-type","errorCode":null,"errorMessage":"read an Array from a non-Array data type","messagePattern":"read an Array from a non-Array data type","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/polars-json/src/json/deserialize.rs","lineNumber":551,"sourceCode":"            allow_extra_fields_in_struct,\n        )?)),\n        adt => polars_bail!(\n            ComputeError: \"deserialization from JSON is not implemented for `{adt:?}`\"\n        ),\n    }\n}\n\npub fn deserialize(\n    json: &BorrowedValue,\n    dtype: ArrowDataType,\n    allow_extra_fields_in_struct: bool,\n) -> PolarsResult<Box<dyn Array>> {\n    match json {\n        BorrowedValue::Array(rows) => match dtype {\n            ArrowDataType::LargeList(inner) => {\n                _deserialize(rows, inner.dtype, allow_extra_fields_in_struct)\n            },\n            _ => todo!(\"read an Array from a non-Array data type\"),\n        },\n        _ => _deserialize(&[json], dtype, allow_extra_fields_in_struct),\n    }\n}\n\nfn check_err_idx<'a>(\n    rows: &[impl Borrow<BorrowedValue<'a>>],\n    err_idx: usize,\n    type_name: &'static str,\n) -> PolarsResult<()> {\n    if err_idx != rows.len() {\n        polars_bail!(\n            ComputeError:\n            r#\"error deserializing value \"{:?}\" as {}.\n\nTry increasing `infer_schema_length` or specifying a schema.\"#,\n            rows[err_idx].borrow(), type_name,\n        )","sourceCodeStart":533,"sourceCodeEnd":569,"githubUrl":"https://github.com/pola-rs/polars/blob/68506541d2de983056c9eb244e1ea05fab377dfc/crates/polars-json/src/json/deserialize.rs#L533-L569","documentation":"The public json::deserialize(json, dtype, ...) requires that when the top-level JSON value is an Array, the target dtype is LargeList - it dispatches to _deserialize on the inner elements. Any other dtype with an array root hits todo!(). It is a caller-contract violation: array-shaped JSON must target a list type; scalar dtypes must be fed element-wise (which is what internal callers do).","triggerScenarios":"Calling polars_json::json::deserialize(&borrowed_value, ArrowDataType::Int64, ...) where borrowed_value is a JSON array like [1,2,3]; custom integrations that pass serde/simd-json parsed bodies straight through without checking the root shape.","commonSituations":"Hand-rolled interop feeding arbitrary JSON bodies to deserialize; assuming lenient coercion (array -> first element, single-element array -> scalar).","solutions":["Wrap the target dtype: pass ArrowDataType::LargeList(inner) when the root is an array","Or flatten first: iterate the array and call deserialize per element with the scalar dtype","Check the root variant (BorrowedValue::Array vs other) before choosing the dtype"],"exampleFix":"// before\ndeserialize(&json_array, ArrowDataType::Int64, true)  // todo!()\n\n// after\ndeserialize(&json_array, ArrowDataType::LargeList(Box::new(Field::new(\"item\", ArrowDataType::Int64, true))), true)\n// or: for v in array_elements { deserialize(&v, ArrowDataType::Int64, true)?; }","handlingStrategy":"type-guard","validationCode":"use polars_json::json::BorrowedValue;\nfn root_matches_dtype(v: &BorrowedValue, dtype: &ArrowDataType) -> bool {\n    match (v, dtype) {\n        (BorrowedValue::Array(_), ArrowDataType::LargeList(_)) => true,\n        (BorrowedValue::Array(_), _) => false,\n        (_, ArrowDataType::LargeList(_)) => false,\n        _ => true,\n    }\n}","typeGuard":"fn target_dtype_for_root(v: &BorrowedValue, elem: ArrowDataType) -> ArrowDataType {\n    match v {\n        BorrowedValue::Array(_) => ArrowDataType::LargeList(Box::new(\n            ArrowField::new(\"item\", elem, true).into(),\n        )),\n        _ => elem,\n    }\n}","tryCatchPattern":null,"preventionTips":["Never pass unshaped serde/simd-json bodies straight to deserialize - branch on the root variant first","Wrap one-line shape checks in the interop layer where JSON meets Arrow dtypes","Add tests covering array roots, scalar roots and mismatched dtypes"],"tags":["polars","json","deserialization","type-mismatch","arrow"],"backgroundTag":"json-type-mismatch","analyzedSha":"68506541d2de983056c9eb244e1ea05fab377dfc","analyzedAt":"2026-08-19T12:15:06.350Z","contentChangedAt":"2026-08-19T12:15:06.350Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}