risingwavelabs/risingwave · error · HummockError

Magic number mismatch: expected {expected}, found: {found}

Error message

Magic number mismatch: expected {expected}, found: {found}

What it means

HummockErrorInner::MagicMismatch is raised when deserializing Hummock-internal persisted structures (SST/block data, meta files, protobuf payloads with a magic header) whose leading magic number doesn't match the expected constant. It indicates the bytes being read are not the expected file format — wrong file, corruption, or a format/version mismatch.

Source

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

//     http://www.apache.org/licenses/LICENSE-2.0
//
// 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}")]

View on GitHub (pinned to 6469eb736d)

Solutions

1. Verify the object/file being read is a genuine Hummock artifact of the expected type — check the 'found' value in the message against known magic constants.
2. Check whether the file is truncated or corrupted (compare size/checksum with the object store manifest) and re-upload/recover it if possible.
3. Confirm all RisingWave nodes run a compatible version; incompatible internal formats across versions can change serialization layout.
4. If corruption is confirmed on the object store, restore from backup or trigger meta to re-generate/rebuild the affected SST (e.g. re-run compaction or rebuild the table from source).

async fn file_is_valid_hummock_artifact(store: &ObjectStore, path: &str, expected_magic: u32) -> bool {
    match store.read(path, ..8).await {
        Ok(bytes) => u32::from_le_bytes(bytes[0..4].try_into().unwrap()) == expected_magic,
        Err(_) => false,
    }
}

match deserialize_artifact(&bytes) {
    Ok(a) => use(a),
    Err(e) if matches!(e.root_cause(), HummockErrorInner::MagicMismatch { .. }) => {
        tracing::error!("corrupt/foreign artifact: {e}");
        quarantine_and_rebuild(path);
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Reading an SST, block, or other Hummock persisted artifact whose header bytes differ from the expected magic constant (expected vs found are included in the error), typically during compaction, replication, or recovery reads.

Common situations: Pointing a node at a data directory from an incompatible RisingWave version; a truncated or corrupted object-store file (partial upload, S3/MinIO issue); hand-copied or mixed data files between clusters.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• SST {0} is invalid
• metadata JSON payload length exceeds usize
• Hummock error: {0}
• Serialize/deserialize error: {0}
• Unsupported task type for copy-on-write iceberg compaction:

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