influxdata/influxdb · error · Error

WAL file too small: expected at least

Error message

WAL file too small: expected at least {expected} bytes, but got {actual} bytes

What it means

serialize::Error::WalFileTooSmall is thrown when a WAL file has fewer bytes than the minimum required to hold the header (magic identifier + size fields), with the expected and actual byte counts in the message. The reader needs at least the fixed-size identifier block before it can even validate the file; anything smaller cannot be a valid WAL file.

Solutions

1. Delete or quarantine the too-small WAL file — it contains no recoverable segment data; the WAL will resume from valid files.
2. Restore the file from a backup if the data matters.
3. Fix the underlying disk-space or crash condition so new files are fully written.
4. Add monitoring for zero-length WAL files after unclean shutdowns so they are cleaned before readers trip on them.

Example fix

# before: crash-left empty file blocks replay
ls wal/1/1712345678/0000000007.wal  # 0 bytes -> WalFileTooSmall { expected: N, actual: 0 }
# after: remove the empty file, restart
rm wal/1/1712345678/0000000007.wal

// pre-check file size against the header minimum before deserializing
let meta = std::fs::metadata(path)?;
if meta.len() < MIN_HEADER_SIZE as u64 {
    // too small to be a WAL file: quarantine/delete
}

fn is_plausible_wal(path: &Path) -> bool {
    std::fs::metadata(path).map(|m| m.len() >= MIN_HEADER_SIZE as u64).unwrap_or(false)
}

match verify_file_type_and_deserialize(&bytes) {
    Err(serialize::Error::WalFileTooSmall { expected, actual }) => {
        // zero/short file from crash: remove and continue replay
    }
    other => other?,
}

When it happens

Trigger: verify_file_type_and_deserialize reads a file whose length is below the required minimum header size (serialize.rs:48-60, error constructed around lines 86-98); this happens on zero-length files created by crashes mid-create, and on files truncated below the header size.

Common situations: Disk-full conditions leaving an empty .wal file; a process killed between file creation and first write; rsync/backup tooling copying partial files; manual truncation with head/echo during debugging.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

• crc32 checksum mismatch
• Invalid wal file identifier
• try from slice error
• bitcode error
• deserialize error

AI-assisted analysis of influxdata/influxdb@06200ef96b (2026-09-19). Data as JSON: /api/errors/77a715d535a98c48. Report an issue: GitHub.

Appendix: source

Thrown at influxdb3_wal/src/serialize.rs:17

//! Module for serializing and deserializing the contents of a single WAL file. Since the WAL is
//! buffered in memory before writing it in a single PUT operation to object store, this works
//! a little differently than a traditional WAL that appends.

use crate::WalContents;
use byteorder::{BigEndian, ReadBytesExt};
use bytes::Bytes;
use std::io::Cursor;
use std::mem::size_of;
use thiserror::Error;

#[derive(Debug, Error)]
pub enum Error {
    #[error("Invalid wal file identifier")]
    InvalidWalFile,

    #[error("WAL file too small: expected at least {expected} bytes, but got {actual} bytes")]
    WalFileTooSmall { expected: usize, actual: usize },

    #[error("crc32 checksum mismatch")]
    Crc32Mismatch,

    #[error("bitcode error: {0}")]
    Bitcode(#[from] bitcode::Error),

    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),

    #[error("try from slice error {0}")]
    TryFromSlice(#[from] std::array::TryFromSliceError),
}

pub(crate) type Result<T, E = Error> = std::result::Result<T, E>;

/// The first bytes written into a wal file to identify it and its version.

View on GitHub (pinned to 06200ef96b)