quickwit-oss/tantivy · error

mmap cache lock is poisoned

Error message

mmap cache lock is poisoned

What it means

Fires in MmapDirectory::get_cache_info when taking the write lock on the mmap cache to prune dead weak references. The RwLock is poisoned — some thread panicked while holding it — so cache statistics cannot be safely computed. This is a poisoned-lock sentinel rather than a data validation failure; note the follow-up read() on the same lock carries a similar message, so either acquisition can surface this failure in cache introspection.

Source

Thrown at src/directory/mmap_directory/mod.rs:296

        Ok(MmapDirectory::new(canonical_path, None))
    }

    /// Joins a relative_path to the directory `root_path`
    /// to create a proper complete `filepath`.
    fn resolve_path(&self, relative_path: &Path) -> PathBuf {
        self.inner.root_path.join(relative_path)
    }

    /// Returns some statistical information
    /// about the Mmap cache.
    ///
    /// The `MmapDirectory` embeds a `MmapDirectory`
    /// to avoid multiplying the `mmap` system calls.
    pub fn get_cache_info(&self) -> CacheInfo {
        self.inner
            .mmap_cache
            .write()
            .expect("mmap cache lock is poisoned")
            .remove_weak_ref();
        self.inner
            .mmap_cache
            .read()
            .expect("Mmap cache lock is poisoned.")
            .get_info()
    }
}

/// We rely on fs2 for file locking. On Windows & MacOS this
/// uses BSD locks (`flock`). The lock is actually released when
/// the `File` object is dropped and its associated file descriptor
/// is closed.
struct ReleaseLockFile {
    _file: File,
    path: PathBuf,
}

View on GitHub (pinned to b5d8deb80c)

Solutions

1. Find the original panic that poisoned the mmap_cache lock (review logs from the crashing thread)
2. Avoid panicking while holding the cache lock; propagate errors as Results
3. Recover with PoisonError::into_inner if best-effort cache info is acceptable

When it happens

Trigger: Thrown at src/directory/mmap_directory/mod.rs:296 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of quickwit-oss/tantivy@b5d8deb80c (2026-09-05). Data as JSON: /api/errors/3a99e76086d5402e. Report an issue: GitHub.