{"record":{"id":"33810420fc4647c6","repo":"pola-rs/polars","slug":"structarray-must-be-initialized-with-datatype-str","errorCode":null,"errorMessage":"StructArray must be initialized with DataType::Struct","messagePattern":"StructArray must be initialized with DataType::Struct","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/polars-arrow/src/array/struct_/mod.rs","lineNumber":134,"sourceCode":"    pub fn new(\n        dtype: ArrowDataType,\n        length: usize,\n        values: Vec<Box<dyn Array>>,\n        validity: Option<Bitmap>,\n    ) -> Self {\n        Self::try_new(dtype, length, values, validity).unwrap()\n    }\n\n    /// Creates an empty [`StructArray`].\n    pub fn new_empty(dtype: ArrowDataType) -> Self {\n        if let ArrowDataType::Struct(fields) = &dtype.to_storage() {\n            let values = fields\n                .iter()\n                .map(|field| new_empty_array(field.dtype().clone()))\n                .collect();\n            Self::new(dtype, 0, values, None)\n        } else {\n            panic!(\"StructArray must be initialized with DataType::Struct\");\n        }\n    }\n\n    /// Creates a null [`StructArray`] of length `length`.\n    pub fn new_null(dtype: ArrowDataType, length: usize) -> Self {\n        if let ArrowDataType::Struct(fields) = &dtype {\n            let values = fields\n                .iter()\n                .map(|field| new_null_array(field.dtype().clone(), length))\n                .collect();\n            Self::new(dtype, length, values, Some(Bitmap::new_zeroed(length)))\n        } else {\n            panic!(\"StructArray must be initialized with DataType::Struct\");\n        }\n    }\n}\n\n// must use","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/pola-rs/polars/blob/9b5d73fd00236295624374b075d16b1fe6ec6df9/crates/polars-arrow/src/array/struct_/mod.rs#L116-L152","documentation":"StructArray::new_empty only accepts an ArrowDataType whose to_storage() is Struct(fields): it needs the field list to build one empty child array per field. Any other dtype panics because there is no field set to construct children from.","triggerScenarios":"StructArray::new_empty(ArrowDataType::Null) or new_empty(List(..)) — usually reached from generic code that special-cases struct handling but falls through to the concrete constructor for non-struct dtypes.","commonSituations":"Schema evolution delivering a non-struct dtype where code assumed structs; matching on a logical/extension type whose storage is not Struct; copy-pasted empty-batch construction for heterogeneous schemas.","solutions":["Use the generic dispatcher polars_arrow::array::new_empty_array(dtype) instead of calling StructArray::new_empty directly","Match on matches!(dtype.to_storage(), ArrowDataType::Struct(_)) before calling and handle other variants explicitly","Return a proper unsupported-dtype error for unexpected variants instead of reaching the panic"],"exampleFix":"// before\nlet empty = StructArray::new_empty(dtype);\n\n// after\nlet empty = polars_arrow::array::new_empty_array(dtype);","handlingStrategy":"type-guard","validationCode":"fn struct_only(dtype: &ArrowDataType) -> Result<&ArrowDataType, String> {\n    match dtype.to_storage() {\n        ArrowDataType::Struct(_) => Ok(dtype),\n        other => Err(format!(\"expected Struct dtype, got {other:?}\")),\n    }\n}","typeGuard":"fn is_struct_dtype(dtype: &ArrowDataType) -> bool {\n    matches!(dtype.to_storage(), ArrowDataType::Struct(_))\n}","tryCatchPattern":null,"preventionTips":["Prefer polars_arrow::array::new_empty_array(dtype) over concrete constructors in generic code","Handle every dtype variant explicitly in empty/null array factories","Treat schema-driven dtypes as unvalidated input: match before dispatch"],"tags":["rust","polars","arrow","struct-array","dtype"],"backgroundTag":"dtype-mismatch","analyzedSha":"9b5d73fd00236295624374b075d16b1fe6ec6df9","analyzedAt":"2026-08-19T12:15:06.350Z","contentChangedAt":"2026-08-19T12:15:06.350Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}