risingwavelabs/risingwave · error · HummockError

FileCache error: {0}

Error message

FileCache error: {0}

What it means

This is the HummockError::FileCache variant of RisingWave's Hummock storage error enum, defined in src/storage/src/hummock/error.rs:67-68. It wraps a string produced by the file cache subsystem (the disk/durable block cache layer used for reading SST blocks, constructed via HummockError::file_cache at error.rs:169-171). It indicates the underlying file cache operation (lookup, insert, eviction, or I/O against cached files) failed.

Source

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

    #[error("Next epoch error: {0}")]
    NextEpoch(String),
    #[error("Change log retention miss: table {table_id}, epoch {epoch}")]
    ChangeLogRetentionMiss { table_id: TableId, epoch: u64 },
    #[error("Time-travel version expired: table {table_id}, epoch {epoch}")]
    TimeTravelVersionExpired { table_id: TableId, epoch: u64 },
    #[error(
        "Committed epoch mismatch: table {table_id}, committed_epoch {committed_epoch}, read_epoch {read_epoch}"
    )]
    CommittedEpochMismatch {
        table_id: TableId,
        committed_epoch: u64,
        read_epoch: u64,
    },
    #[error("Barrier read is unavailable for now. Likely the cluster is recovering")]
    ReadCurrentEpoch,
    #[error("CompactionExecutor error: {0}")]
    CompactionExecutor(String),
    #[error("FileCache error: {0}")]
    FileCache(String),
    #[error("SstObjectIdTracker error: {0}")]
    SstObjectIdTrackerError(String),
    #[error("CompactionGroup error: {0}")]
    CompactionGroupError(String),
    #[error("SstableUpload error: {0}")]
    SstableUploadError(String),
    #[error("Read backup error: {0}")]
    ReadBackupError(String),
    #[error("Foyer error: {0}")]
    FoyerError(#[from] foyer::Error),
    #[error("Other error: {0}")]
    Other(String),
}

impl HummockError {
    pub fn invalid_format_version(v: u32) -> HummockError {
        HummockErrorInner::InvalidFormatVersion(v).into()

View on GitHub (pinned to 6469eb736d)

Solutions

1. Check the file cache directory (disk space, permissions, mount) referenced in the storage config and fix the underlying I/O problem
2. Clear the file cache directory so stale/corrupt cache files are rebuilt; safe because the cache is derived data
3. Verify cache-related config values (cache directory, capacity) are valid and consistent with the deployed version
4. If persistent, capture the inner string for the report and restart the node; escalate with the full error report

Example fix

// before: opaque FileCache error in logs, cache dir on a nearly-full volume
// after: ensure the cache dir exists with space, then clean stale cache files
rm -rf <state_store_data_dir>/file_cache
# and monitor disk usage of the cache volume

// before enabling file cache, validate the cache directory
let dir = config.file_cache_dir.clone();
assert!(!dir.is_empty(), "file cache dir must be set");
let meta = tokio::fs::metadata(&dir).await.expect("cache dir must exist");
assert!(meta.is_dir(), "file cache path is not a directory");

fn is_file_cache_err(e: &HummockError) -> bool {
    e.to_report_string().starts_with("FileCache error:")
}

match hummock_read().await {
    Err(e) if is_file_cache_err(&e) => {
        // cache is derived data: clean cache dir and retry; storage itself is intact
        warn!(error = %e.report(), "file cache failed; retrying");
        clear_cache_dir();
        hummock_read().await
    }
    other => other,
}

When it happens

Trigger: A call into Hummock's file-cache read/write path fails, e.g. a cached-file lookup returns an error, the cache file is corrupted or the cache data directory is unreadable/writable, and the component converts that error via HummockError::file_cache("...").

Common situations: Disk full or permission errors on the file cache directory; stale/corrupted cache files after an unclean shutdown or version upgrade; misconfigured cache directory path in the config.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• ObjectStore failed with IO error: {0}
• Storage error: {0}
• check if version hint exist failed: {}
• Fail to check exist
• (dataset guard acquisition error)

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