risingwavelabs/risingwave · critical · HummockError

Invalid format version

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.

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

• Decode error
• Encode error
• Magic number mismatch: expected
• Barrier read is unavailable for now. Likely the cluster is…
• Change log retention miss: table

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

Appendix: 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)