{"record":{"id":"e053f3282289dfb3","repo":"risingwavelabs/risingwave","slug":"filecache-error-0","errorCode":null,"errorMessage":"FileCache error: {0}","messagePattern":"FileCache error: (.+?)","errorType":"exception","errorClass":"HummockError","httpStatus":null,"severity":"error","filePath":"src/storage/src/hummock/error.rs","lineNumber":67,"sourceCode":"    #[error(\"Next epoch error: {0}\")]\n    NextEpoch(String),\n    #[error(\"Change log retention miss: table {table_id}, epoch {epoch}\")]\n    ChangeLogRetentionMiss { table_id: TableId, epoch: u64 },\n    #[error(\"Time-travel version expired: table {table_id}, epoch {epoch}\")]\n    TimeTravelVersionExpired { table_id: TableId, epoch: u64 },\n    #[error(\n        \"Committed epoch mismatch: table {table_id}, committed_epoch {committed_epoch}, read_epoch {read_epoch}\"\n    )]\n    CommittedEpochMismatch {\n        table_id: TableId,\n        committed_epoch: u64,\n        read_epoch: u64,\n    },\n    #[error(\"Barrier read is unavailable for now. Likely the cluster is recovering\")]\n    ReadCurrentEpoch,\n    #[error(\"CompactionExecutor error: {0}\")]\n    CompactionExecutor(String),\n    #[error(\"FileCache error: {0}\")]\n    FileCache(String),\n    #[error(\"SstObjectIdTracker error: {0}\")]\n    SstObjectIdTrackerError(String),\n    #[error(\"CompactionGroup error: {0}\")]\n    CompactionGroupError(String),\n    #[error(\"SstableUpload error: {0}\")]\n    SstableUploadError(String),\n    #[error(\"Read backup error: {0}\")]\n    ReadBackupError(String),\n    #[error(\"Foyer error: {0}\")]\n    FoyerError(#[from] foyer::Error),\n    #[error(\"Other error: {0}\")]\n    Other(String),\n}\n\nimpl HummockError {\n    pub fn invalid_format_version(v: u32) -> HummockError {\n        HummockErrorInner::InvalidFormatVersion(v).into()","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/risingwavelabs/risingwave/blob/6469eb736d691e8e9b8a419a57edd6429ca77417/src/storage/src/hummock/error.rs#L49-L85","documentation":"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.","triggerScenarios":"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(\"...\").","commonSituations":"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.","solutions":["Check the file cache directory (disk space, permissions, mount) referenced in the storage config and fix the underlying I/O problem","Clear the file cache directory so stale/corrupt cache files are rebuilt; safe because the cache is derived data","Verify cache-related config values (cache directory, capacity) are valid and consistent with the deployed version","If persistent, capture the inner string for the report and restart the node; escalate with the full error report"],"exampleFix":"// before: opaque FileCache error in logs, cache dir on a nearly-full volume\n// after: ensure the cache dir exists with space, then clean stale cache files\nrm -rf <state_store_data_dir>/file_cache\n# and monitor disk usage of the cache volume","handlingStrategy":"retry","validationCode":"// before enabling file cache, validate the cache directory\nlet dir = config.file_cache_dir.clone();\nassert!(!dir.is_empty(), \"file cache dir must be set\");\nlet meta = tokio::fs::metadata(&dir).await.expect(\"cache dir must exist\");\nassert!(meta.is_dir(), \"file cache path is not a directory\");","typeGuard":"fn is_file_cache_err(e: &HummockError) -> bool {\n    e.to_report_string().starts_with(\"FileCache error:\")\n}","tryCatchPattern":"match hummock_read().await {\n    Err(e) if is_file_cache_err(&e) => {\n        // cache is derived data: clean cache dir and retry; storage itself is intact\n        warn!(error = %e.report(), \"file cache failed; retrying\");\n        clear_cache_dir();\n        hummock_read().await\n    }\n    other => other,\n}","preventionTips":["Provision the file cache volume with ample free space and monitoring on disk usage","Set correct permissions on the cache directory for the risingwave process user","Clean the cache directory after unclean shutdowns or version upgrades","Pin cache-related config to values documented for your RisingWave version"],"tags":["storage","hummock","file-cache","io"],"backgroundTag":"file-read-failed","analyzedSha":"6469eb736d691e8e9b8a419a57edd6429ca77417","analyzedAt":"2026-09-11T21:06:21.487Z","contentChangedAt":"2026-09-11T21:06:21.487Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}