facebook/flow · error

failed to deserialize Docblock

Error message

failed to deserialize Docblock

What it means

Panics when bincode fails to decode a Docblock from decompressed bytes. Like the other round-trips in this crate, the file_key thread-local is set for Loc resolution and the tuple returned by decode_from_slice must consume exactly the whole slice. Corruption or schema drift between writer and reader lands here.

Source

Thrown at rust_port/crates/flow_heap_serialization/src/lib.rs:69

    let (ast, _): (Program<Loc, Loc>, _) =
        bincode::serde::decode_from_slice(&decompressed, bincode::config::legacy())
            .expect("failed to deserialize AST");
    clear_file_key();
    Arc::new(ast)
}

pub fn serialize_docblock(docblock: &Docblock) -> Vec<u8> {
    let bytes = bincode::serde::encode_to_vec(docblock, bincode::config::legacy())
        .expect("failed to serialize Docblock");
    compress(&bytes)
}

pub fn deserialize_docblock(file_key: &FileKey, bytes: &[u8]) -> Arc<Docblock> {
    let decompressed = decompress(bytes);
    set_file_key(file_key);
    let (docblock, _): (Docblock, _) =
        bincode::serde::decode_from_slice(&decompressed, bincode::config::legacy())
            .expect("failed to deserialize Docblock");
    clear_file_key();
    Arc::new(docblock)
}

pub fn serialize_aloc_table(table: &PackedALocTable) -> Vec<u8> {
    let bytes = bincode::serde::encode_to_vec(table, bincode::config::legacy())
        .expect("failed to serialize PackedALocTable");
    compress(&bytes)
}

pub fn deserialize_aloc_table(bytes: &[u8]) -> Arc<PackedALocTable> {
    let decompressed = decompress(bytes);
    let (table, _): (PackedALocTable, _) =
        bincode::serde::decode_from_slice(&decompressed, bincode::config::legacy())
            .expect("failed to deserialize PackedALocTable");
    Arc::new(table)
}

View on GitHub (pinned to f88ac94bcf)

Solutions

1. Clear the docblock/heap cache entries so they are recomputed
2. Keep one cache directory per flow version (version-stamped cache paths)
3. Regenerate fixtures after changing any serialized type in Docblock

match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
    flow_heap_serialization::deserialize_docblock(&file_key, &bytes)
})) {
    Ok(doc) => doc,
    Err(_) => { std::fs::remove_file(&cache_path).ok(); reparse_docblock(&file_key)? }
}

When it happens

Trigger: deserialize_docblock on cache bytes truncated mid-record or written by a different flow build; a Docblock format change (new field/variant) without cache invalidation; wrong file passed in (bytes are a different record type that happens to decompress).

Common situations: Upgrading flow while keeping the old saved-state directory; caches shared across checkout directories with mixed versions; non-atomic cache writes from killed processes.

Related errors

• failed to deserialize AST
• failed to deserialize PackedALocTable
• failed to deserialize type sig Module
• failed to deserialize FileSig
• failed to deserialize Exports

AI-assisted analysis of facebook/flow@f88ac94bcf (2026-08-20). Data as JSON: /api/errors/479a5a6db763acac. Report an issue: GitHub.