quickwit-oss/quickwit · error

file byte range cache mutex is poisoned

Error message

file byte range cache mutex is poisoned

What it means

`FileByteRangeCache::get_slice` locked the per-file cache state mutex and the lock returned a poison error, meaning another thread panicked while holding this mutex. The `.expect` then panics in turn. The original panic happened elsewhere; this message only tells you the cache state is unusable.

Solutions

1. Look further up in the logs for the panic that poisoned the mutex — that is the real failure
2. Restart the searcher process/node to recover a clean cache state
3. Report the original panic to Quickwit maintainers if it looks like a bug

When it happens

Trigger: Thrown at quickwit/quickwit-storage/src/cache/byte_range_cache.rs:210 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of quickwit-oss/quickwit@a39730c5cd (2026-09-08). Data as JSON: /api/errors/3fbf8ef3048b4f12. Report an issue: GitHub.

Appendix: source

Thrown at quickwit/quickwit-storage/src/cache/byte_range_cache.rs:210

#[derive(Clone)]
pub struct FileByteRangeCache {
    state: Arc<Mutex<FileByteRangeCacheState>>,
    total_num_stored_bytes: Arc<AtomicU64>,
}

impl FileByteRangeCache {
    fn with_total_num_stored_bytes(total_num_stored_bytes: Arc<AtomicU64>) -> Self {
        FileByteRangeCache {
            state: Arc::new(Mutex::new(FileByteRangeCacheState::with_infinite_capacity())),
            total_num_stored_bytes,
        }
    }

    /// Returns the cached view of the slice if it is available.
    pub fn get_slice(&self, byte_range: Range<usize>) -> Option<OwnedBytes> {
        self.state
            .lock()
            .expect("file byte range cache mutex is poisoned")
            .get_slice(byte_range)
    }

    /// Stores the given slice in the cache.
    pub fn put_slice(&self, byte_range: Range<usize>, bytes: OwnedBytes) {
        let mut state = self
            .state
            .lock()
            .expect("file byte range cache mutex is poisoned");
        let previous_num_bytes = state.num_bytes;
        state.put_slice(byte_range, bytes);
        let num_added_bytes = state.num_bytes - previous_num_bytes;
        self.total_num_stored_bytes
            .fetch_add(num_added_bytes, Ordering::Relaxed);
    }
}

/// Cache for ranges of bytes in files.

View on GitHub (pinned to a39730c5cd)