What causes "Foyer error: {0}" in risingwavelabs/risingwave?

Inspect the inner foyer::Error message (the {0} payload) for the root cause

risingwavelabs/risingwave · error · HummockError

Foyer error

Error message

Foyer error: {0}

What it means

A Hummock (RisingWave storage engine) error wrapping a foyer (cache) library failure via #[from]. It is converted automatically whenever any foyer cache operation fails, e.g. cache lookups, insertions, or reinsertions.

Solutions

Inspect the inner foyer::Error message (the {0} payload) for the root cause
Check the foyer cache directory permissions, disk space, and configuration (capacity, path)
Update or pin foyer to a compatible version matching RisingWave's dependency tree
If reproducible, file an issue with the wrapped foyer error details

Defensive patterns

Strategy: try-catch

Validate before calling

// No pre-call validation possible for internal cache failures.
// Ensure cache dir exists and is writable at startup:
// std::fs::create_dir_all(&cache_dir)?;

Try / catch

match result {
    Err(e) if matches!(e.as_ref(), HummockError::FoyerError(_)) => {
        tracing::warn!(error = ?e, "foyer cache failure");
        // fall back to non-cached read path
    }
    other => other?,
}

Prevention

Verify foyer cache configuration (path, capacity) before startup
Monitor disk space and permissions on cache directories
Pin foyer dependency versions to those tested with your RisingWave build

When it happens

Trigger: Any code path that interacts with the foyer cache (read/write through the block or meta cache) surfaces an underlying foyer::Error, which is auto-converted into HummockError::FoyerError.

Common situations: Disk or memory cache backend misconfiguration, I/O failures on the cache directory, cache eviction/internal foyer invariants violated, or incompatible foyer versions after dependency upgrades.

Related errors

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

Appendix: source

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

        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()
    }

    pub fn invalid_block() -> HummockError {
        HummockErrorInner::InvalidBlock.into()
    }

    pub fn encode_error(error: impl ToString) -> HummockError {
        HummockErrorInner::EncodeError(error.to_string()).into()
    }

View on GitHub (pinned to 6469eb736d)