{"record":{"id":"39389be76e14073b","repo":"facebook/flow","slug":"hh-load-heap-invalid-magic-number","errorCode":null,"errorMessage":"hh_load_heap: invalid magic number","messagePattern":"hh_load_heap: invalid magic number","errorType":"exception","errorClass":"std::io::Error","httpStatus":null,"severity":"error","filePath":"rust_port/crates/flow_heap/src/transaction.rs","lineNumber":1266,"sourceCode":"        self.stage_heap_replacement(data);\n        Ok(())\n    }\n\n    pub(crate) fn read_heap(reader: &mut impl Read) -> std::io::Result<CommittedHeapData> {\n        let header: SerializedHeapHeader = decode_from_reader(reader)?;\n        Self::validate_serialized_heap_header(&header, HEAP_MAGIC_RUST_SHARDED_LOCAL_INDEXED_LZ4)?;\n        Self::read_heap_shards(reader, None)\n    }\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)","sourceCodeStart":1248,"sourceCodeEnd":1284,"githubUrl":"https://github.com/facebook/flow/blob/f88ac94bcf6992f5d5a158854d94613ebb92c6e6/rust_port/crates/flow_heap/src/transaction.rs#L1248-L1284","documentation":"A serialized Flow heap starts with a SerializedHeapHeader whose magic number pins the exact binary format. read_heap_with_file_table accepts only the two magics this build understands (RUST_SHARDED_LOCAL_INDEXED_LZ4 and the EXTERNAL_FILES variant); any other leading bytes return ErrorKind::InvalidData \"hh_load_heap: invalid magic number\". The file is not a heap this build can read — wrong format, wrong version, or not a heap at all.","triggerScenarios":"Pointing hh_load_heap/read_heap at a file that is not a saved heap (random/text file passed where a heap is expected), a truncated file whose header is garbage, or a heap written by a build whose format magic differs from the reader's.","commonSituations":"Reusing saved-state files across Flow versions that changed the heap format; a zero-byte heap left by a crashed first save; copied/moved artifacts whose names match but contents do not.","solutions":["Delete the offending heap/saved-state file and let Flow regenerate it from sources.","Confirm the reader and writer are the same Flow build — mixed versions in PATH or CI caches are the usual cause.","Check the file size and first bytes: a 0-byte or text file where a heap is expected means the path is wrong."],"exampleFix":"# before: heap written by an older/newer build -> invalid magic number\nflow check\n\n# after: remove mismatched saved state and rebuild\nrm -rf .flow-saved-state   # or your configured saved-state directory\nflow check","handlingStrategy":"fallback","validationCode":null,"typeGuard":"fn is_invalid_heap_magic(e: &std::io::Error) -> bool {\n    e.kind() == std::io::ErrorKind::InvalidData && e.to_string().contains(\"invalid magic number\")\n}","tryCatchPattern":"On InvalidData 'invalid magic number', fall back to a cold start: delete/regenerate the saved heap and rebuild. Log which file failed so operators can spot version-skew patterns across a fleet.","preventionTips":["Key saved-state paths by Flow version and heap format.","Write-then-rename when persisting heaps so readers never see partial files.","Fail fast on 0-byte heap files before attempting to parse them."],"tags":["heap","serialization","magic-number","corruption","rust"],"backgroundTag":"invalid-magic-number","analyzedSha":"f88ac94bcf6992f5d5a158854d94613ebb92c6e6","analyzedAt":"2026-08-20T10:41:37.992Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}