databendlabs/databend · critical

The header tree can only contain DataHeader

Error message

The header tree can only contain DataHeader

What it means

read_version reads the data version from the 'header' Raft tree. It asserts the header key equals 'header' and panics with unreachable!("The header tree can only contain DataHeader") if the entry is any other RaftStoreEntry variant. The invariant is that the TREE_HEADER tree stores only DataHeader entries carrying an explicit version.

Solutions

1. Inspect the offending header-tree entry and repair or remove the invalid record.
2. Ensure all writers only store RaftStoreEntry::DataHeader (key 'header') in TREE_HEADER.
3. If this appears after an upgrade/downgrade, restore the data directory from a compatible backup instead of replaying it.

Example fix

// before
_ => unreachable!("The header tree can only contain DataHeader"),
// after
other => return Err(anyhow!("header tree contains non-DataHeader entry: {:?}", other)),

fn is_data_header(entry: &RaftStoreEntry) -> bool {
    matches!(entry, RaftStoreEntry::DataHeader { .. })
}

let version = match &kv_entry {
    RaftStoreEntry::DataHeader { key, value } if key == "header" => value.0.version,
    other => {
        error!("invalid header tree entry: {:?}", other);
        return Err(Error::CorruptedHeaderTree);
    }
};

When it happens

Trigger: Reading an entry from the header tree that is not RaftStoreEntry::DataHeader — e.g. corrupted/legacy on-disk data, a writer that stored a wrong entry type in the header tree, or entries written by an older version before the DataHeader format existed.

Common situations: Opening a meta-service data directory after an upgrade or downgrade across schema versions; disk corruption; hand-copying or merging raft-log directories between nodes.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• failed to decode wkb data
• {}
• Temp table id used up
• Invalid temp table desc
• expect tuple type

AI-assisted analysis of databendlabs/databend@288d84d76e (2026-09-11). Data as JSON: /api/errors/75110344c046128f. Report an issue: GitHub.

Appendix: source

Thrown at src/meta/control/src/reading.rs:65

            "invalid data version: {:?}, This program version is {:?}; The latest compatible program version is: {:?}",
            version,
            DATA_VERSION,
            version.max_compatible_working_version(),
        ));
    }
    Ok(version)
}

pub fn read_version(first_line: &str) -> anyhow::Result<DataVersion> {
    let (tree_name, kv_entry): (String, RaftStoreEntry) = serde_json::from_str(first_line)?;

    let version = if tree_name == TREE_HEADER {
        // There is a explicit header.
        if let RaftStoreEntry::DataHeader { key, value } = &kv_entry {
            assert_eq!(key, "header", "The key can only be 'header'");
            value.0.version
        } else {
            unreachable!("The header tree can only contain DataHeader");
        }
    } else {
        // Without header, the data version is V0 by default.
        DataVersion::V0
    };

    Ok(version)
}

View on GitHub (pinned to 288d84d76e)