{"record":{"id":"e2c0770c43dde7be","repo":"facebook/flow","slug":"hh-load-heap-invalid-shard-count","errorCode":null,"errorMessage":"hh_load_heap: invalid shard count","messagePattern":"hh_load_heap: invalid shard count","errorType":"exception","errorClass":"std::io::Error","httpStatus":null,"severity":"error","filePath":"rust_port/crates/flow_heap/src/transaction.rs","lineNumber":1274,"sourceCode":"    }\n\n    pub(crate) fn read_heap_with_file_table(\n        reader: &mut impl Read,\n        files: Arc<Vec<FileKey>>,\n    ) -> std::io::Result<CommittedHeapData> {\n        let header: SerializedHeapHeader = decode_from_reader(reader)?;\n        if header.magic != HEAP_MAGIC_RUST_SHARDED_LOCAL_INDEXED_LZ4\n            && header.magic != HEAP_MAGIC_RUST_SHARDED_INDEXED_LZ4_EXTERNAL_FILES\n        {\n            return Err(io::Error::new(\n                io::ErrorKind::InvalidData,\n                \"hh_load_heap: invalid magic number\",\n            ));\n        }\n        if header.file_shard_count != GC_MAP_SHARDS as u64\n            || header.haste_module_shard_count != GC_MAP_SHARDS as u64\n        {\n            return Err(io::Error::new(\n                io::ErrorKind::InvalidData,\n                \"hh_load_heap: invalid shard count\",\n            ));\n        }\n        let files = if header.magic == HEAP_MAGIC_RUST_SHARDED_INDEXED_LZ4_EXTERNAL_FILES {\n            Some(files)\n        } else {\n            None\n        };\n        Self::read_heap_shards(reader, files)\n    }\n\n    fn read_heap_shards(\n        reader: &mut impl Read,\n        external_files: Option<Arc<Vec<FileKey>>>,\n    ) -> std::io::Result<CommittedHeapData> {\n        let mut file_shards = Vec::with_capacity(GC_MAP_SHARDS);\n        for _ in 0..GC_MAP_SHARDS {","sourceCodeStart":1256,"sourceCodeEnd":1292,"githubUrl":"https://github.com/facebook/flow/blob/f88ac94bcf6992f5d5a158854d94613ebb92c6e6/rust_port/crates/flow_heap/src/transaction.rs#L1256-L1292","documentation":"After the magic check, read_heap_with_file_table validates the header's file_shard_count and haste_module_shard_count against GC_MAP_SHARDS compiled into this build; both must match exactly. A mismatch returns ErrorKind::InvalidData \"hh_load_heap: invalid shard count\" — the file was written by a build with a different sharding layout, so its shard layout cannot be interpreted.","triggerScenarios":"Loading a heap whose header was written by a Flow build compiled with a different GC_MAP_SHARDS value (format revision between writer and reader), or a hand-corrupted header where the magic happened to match but counts do not.","commonSituations":"Downgrading or upgrading Flow while keeping saved state; a heap file partially rewritten by a crashed save so the header is inconsistent with the body.","solutions":["Delete the saved heap/saved-state artifacts and rebuild from sources.","Ensure one consistent Flow version writes and reads the saved state (check PATH, CI caches, bundled copies).","If rebuilding does not fix it, verify the saved-state directory is writable and not modified by another tool."],"exampleFix":"# before: shard layout from a different build\nflow check\n\n# after: regenerate saved state with the current build\nrm -rf .flow-saved-state   # or your configured saved-state directory\nflow check","handlingStrategy":"fallback","validationCode":null,"typeGuard":"fn is_invalid_shard_count(e: &std::io::Error) -> bool {\n    e.kind() == std::io::ErrorKind::InvalidData && e.to_string().contains(\"invalid shard count\")\n}","tryCatchPattern":"On InvalidData 'invalid shard count', regenerate the saved heap from sources (delete saved state and retry). This is writer/reader format skew — the bytes cannot be repaired in place.","preventionTips":["Bump and check the heap format version together with layout constants like GC_MAP_SHARDS.","Version saved-state directories so incompatible layouts never share paths.","Treat any header-field mismatch as cache invalidation, never a hard failure."],"tags":["heap","serialization","sharding","format-version","rust"],"backgroundTag":"file-format-mismatch","analyzedSha":"f88ac94bcf6992f5d5a158854d94613ebb92c6e6","analyzedAt":"2026-08-20T10:41:37.992Z","schemaVersion":2},"datasetVersion":"2026-08-23T11:17:13.642Z"}