risingwavelabs/risingwave · critical · HummockError

Invalid format version: {0}

Error message

Invalid format version: {0}

What it means

Hummock (RisingWave's storage engine) read a data file (SST/table) whose format version field does not match any version this build understands. The library throws this to prevent reading a file written by an incompatible writer, which would otherwise cause silent corruption. The u32 payload is the version found in the file header.

Source

Thrown at src/storage/src/hummock/error.rs:27

// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

use risingwave_object_store::object::ObjectError;
use risingwave_pb::id::TableId;
use thiserror::Error;
use thiserror_ext::AsReport;
use tokio::sync::oneshot::error::RecvError;

// TODO(error-handling): should prefer use error types than strings.
#[derive(Error, thiserror_ext::ReportDebug, thiserror_ext::Arc)]
#[thiserror_ext(newtype(name = HummockError, backtrace))]
pub enum HummockErrorInner {
    #[error("Magic number mismatch: expected {expected}, found: {found}")]
    MagicMismatch { expected: u32, found: u32 },
    #[error("Invalid format version: {0}")]
    InvalidFormatVersion(u32),
    #[error("Checksum mismatch: expected {expected}, found: {found}")]
    ChecksumMismatch { expected: u64, found: u64 },
    #[error("Invalid block")]
    InvalidBlock,
    #[error("Encode error: {0}")]
    EncodeError(String),
    #[error("Decode error: {0}")]
    DecodeError(String),
    #[error("ObjectStore failed with IO error: {0}")]
    ObjectIoError(
        #[from]
        #[backtrace]
        ObjectError,
    ),
    #[error("Meta error: {0}")]
    MetaError(String),
    #[error("SharedBuffer error: {0}")]

View on GitHub (pinned to 6469eb736d)

Solutions

1. Upgrade RisingWave to the version that wrote the data files (the format version was introduced by a newer release).
2. Check the object store bucket for data written by another cluster/build and point this cluster at the correct bucket.
3. If downgrade was intentional, migrate data through a supported path (e.g. export/import) instead of reusing the same store.
4. Verify no manual tooling or fork wrote the file and inspect the file header to confirm its version.

Example fix

// before: downgraded binary reading SSTs written by newer version
rw config: s3.bucket = rw-prod (shared with v2.0 cluster)
// after
rw config: s3.bucket = rw-prod-v2 (dedicated bucket, or upgrade binary to v2.0)

// Rust
fn is_invalid_format_version(e: &HummockError) -> bool {
    e.as_any().downcast_ref::<HummockError>()
        .map(|h| h.to_string().starts_with("Invalid format version"))
        .unwrap_or(false)
}

// Rust
match hummock_read(...) {
    Err(e) if e.to_string().starts_with("Invalid format version") => {
        // halt service; requires binary upgrade — do not retry
    }
    r => r?,
}

When it happens

Trigger: Reading an SST/block whose serialized header contains an unrecognized format version, typically via Hummock's block/table read path after the version check.

Common situations: Downgrading RisingWave to an older release after newer code wrote data files; mixing binary versions against the same object store; reading data written by a fork or patched build.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Magic number mismatch: expected {expected}, found: {found}
• Encode error: {0}
• Decode error: {0}
• Storage error: {0}
• Storage error: {0}

AI-assisted analysis of risingwavelabs/risingwave@6469eb736d (2026-09-11). Data as JSON: /api/errors/36f0ebf741a5b85f. Report an issue: GitHub.