{"record":{"id":"c7f300079397e07e","repo":"risingwavelabs/risingwave","slug":"invalid-struct-encoding-0","errorCode":null,"errorMessage":"Invalid struct encoding: {0}","messagePattern":"Invalid struct encoding: (.+?)","errorType":"error_code","errorClass":"ValueEncodingError","httpStatus":null,"severity":"error","filePath":"src/common/src/util/value_encoding/error.rs","lineNumber":35,"sourceCode":"#[derive(Error, Debug)]\npub enum ValueEncodingError {\n    #[error(\"Invalid bool value encoding: {0}\")]\n    InvalidBoolEncoding(u8),\n    #[error(\"Invalid UTF8 value encoding: {0}\")]\n    InvalidUtf8(#[from] std::string::FromUtf8Error),\n    #[error(\"Invalid Date value encoding: days: {0}\")]\n    InvalidDateEncoding(i32),\n    #[error(\"invalid Timestamp value encoding: secs: {0} nsecs: {1}\")]\n    InvalidTimestampEncoding(i64, u32),\n    #[error(\"invalid Time value encoding: secs: {0} nano: {1}\")]\n    InvalidTimeEncoding(u32, u32),\n    #[error(\"Invalid null tag value encoding: {0}\")]\n    InvalidTagEncoding(u8),\n    #[error(\"Invalid jsonb encoding\")]\n    InvalidJsonbEncoding,\n    #[error(\"Invalid variant encoding\")]\n    InvalidVariantEncoding,\n    #[error(\"Invalid struct encoding: {0}\")]\n    InvalidStructEncoding(\n        #[source]\n        #[backtrace]\n        crate::array::ArrayError,\n    ),\n    #[error(\"Invalid list encoding: {0}\")]\n    InvalidListEncoding(\n        #[source]\n        #[backtrace]\n        crate::array::ArrayError,\n    ),\n    #[error(\"Invalid flag: {0:b}\")]\n    InvalidFlag(u8),\n    #[error(\"Invalid vector item: {0} {1}\")]\n    InvalidVectorItem(f32, String),\n}\n","sourceCodeStart":17,"sourceCodeEnd":52,"githubUrl":"https://github.com/risingwavelabs/risingwave/blob/6469eb736d691e8e9b8a419a57edd6429ca77417/src/common/src/util/value_encoding/error.rs#L17-L52","documentation":"ValueEncodingError::InvalidStructEncoding wraps a crate::array::ArrayError and is raised when deserializing a struct datum fails. deserialize_struct (src/common/src/util/value_encoding/mod.rs:398-405) decodes each field via inner_deserialize_datum; if any nested field's array/datum decoding errors, it is surfaced as this variant via the wrapped ArrayError source. The inner ArrayError tells you which nested element actually failed.","triggerScenarios":"Decoding a DataType::Struct row whose nested field bytes are truncated or of the wrong type; struct written with a different number/order of fields than the reader's StructType.","commonSituations":"Schema evolution on a struct column (field added/removed/reordered) while old rows are still on disk; version skew between writer and reader; corrupted state-store bytes; NULL/default handling differences across versions.","solutions":["Inspect the wrapped ArrayError source to find the failing nested field","Ensure the reader's StructType matches the schema used when the row was written","Handle schema evolution via column-id based (column-aware) encoding instead of positional struct decoding","Re-materialize affected rows after fixing the schema mismatch"],"exampleFix":"// before: positional struct decode with mismatched schema\nlet v = deserialize_struct(&new_schema, data)?; // InvalidStructEncoding\n// after: decode with the schema recorded for those bytes\nlet stored = StructType::from_stored_field_ids(data)?;\nlet v = deserialize_struct(&stored, data)?;","handlingStrategy":"try-catch","validationCode":"fn struct_type_matches(stored: &StructType, expected: &StructType) -> bool {\n    stored.types().eq(expected.types())\n}","typeGuard":"fn is_compatible_struct(def: &StructType, row_bytes_len: usize, fields: usize) -> bool {\n    def.len() == fields && row_bytes_len >= fields // cheap pre-check before full decode\n}","tryCatchPattern":"match deserialize_datum(&DataType::Struct(def), data) {\n    Ok(v) => { /* use value */ }\n    Err(ValueEncodingError::InvalidStructEncoding(src)) => {\n        tracing::error!(\"struct field decode failed: {src}\"); // inspect ArrayError source\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Inspect the wrapped ArrayError #[source] to pinpoint the failing nested field","Use column-id based column-aware encoding to survive struct schema evolution","Avoid positional struct decoding across schema changes; rewrite rows after schema migration","Pin reader and writer to the same schema version for stored rows"],"tags":["rust","value-encoding","struct","deserialization","schema-mismatch"],"backgroundTag":"schema-validation-failed","analyzedSha":"6469eb736d691e8e9b8a419a57edd6429ca77417","analyzedAt":"2026-09-11T21:06:21.487Z","contentChangedAt":"2026-09-11T21:06:21.487Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}