# Trivy Database Lock Error: How to Fix "Cache May Be in Use by Another Process"

> Fix the Trivy database lock error where the cache is in use by another process. Learn to resolve this issue by switching cache backends or terminating conflicts.

- Repository: [Aqua Security/trivy](https://github.com/aquasecurity/trivy)
- Tags: how-to-guide
- Published: 2026-03-23

---

**The Trivy database lock error occurs when BoltDB's exclusive file lock on the filesystem cache is held by another Trivy process, and you can resolve it by switching to memory or Redis cache backends, terminating competing processes, or using separate cache directories.**

The **Trivy database lock error** typically manifests as "cache may be in use by another process" when scanning with the filesystem cache backend in the `aquasecurity/trivy` repository. This issue originates from the cache implementation in [`pkg/cache/fs.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/cache/fs.go), which uses BoltDB to store scan results and enforces an exclusive OS-level file lock to prevent data corruption during concurrent access.

## What Causes the Trivy Database Lock Error?

The error is triggered by BoltDB's architectural constraint that only one process may hold the database file lock at a time. When a second Trivy instance attempts to access the same cache directory, the lock acquisition fails.

### The BoltDB File Lock Mechanism

In [`pkg/cache/fs.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/cache/fs.go), Trivy implements the **filesystem cache** using BoltDB, an embedded key-value store. According to BoltDB's documentation referenced in [`docs/guide/references/troubleshooting.md`](https://github.com/aquasecurity/trivy/blob/main/docs/guide/references/troubleshooting.md), the library obtains an exclusive file lock via `flock` system calls when opening the database.

Key distinctions regarding lock behavior:

- The **vulnerability database** is opened **read-only** and never causes lock conflicts
- The **filesystem cache** (default for `image`, `filesystem`, and other commands) requires exclusive write access
- Lock contention occurs when multiple processes target the same cache directory (`~/.cache/trivy` by default)

### Common Trigger Scenarios

According to the troubleshooting documentation in [`docs/guide/references/troubleshooting.md`](https://github.com/aquasecurity/trivy/blob/main/docs/guide/references/troubleshooting.md) and the error handling in [`pkg/commands/run.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/commands/run.go), three scenarios typically trigger this error:

1. **Concurrent scans**: Multiple Trivy processes sharing the default cache directory simultaneously
2. **Abnormal termination**: A previous Trivy run crashed or was killed without releasing the filesystem lock
3. **Server mode conflicts**: A long-running `trivy server` process holds the lock while you attempt a local scan

## How to Resolve the Trivy Database Lock Error

### Switch to Memory Cache (Recommended)

The most reliable fix is bypassing the filesystem lock entirely by using the **memory cache backend**. While this is the default for `fs`, `rootfs`, `config`, and `sbom` subcommands, you can force it for other commands to enable concurrent execution:

```bash
trivy image --cache-backend memory debian:11 &
trivy image --cache-backend memory debian:12 &

```

This approach eliminates BoltDB file locks because no database files are accessed on disk, though cache will not persist between runs.

### Configure Redis Cache

For production environments or when running **Trivy server clusters**, configure a Redis backend to allow multiple instances to share cache without file locking:

```bash
trivy server --cache-backend redis://localhost:6379

```

As implemented in the source code and documented in the troubleshooting guide, Redis provides a persistent, distributed cache that eliminates the exclusive file lock constraint entirely.

### Terminate Competing Processes

If you must use filesystem cache, identify the process holding the lock and terminate it before retrying:

```bash
ps aux | grep trivy
kill <process_id>

```

This releases the OS-level file lock in [`pkg/cache/fs.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/cache/fs.go) so the new process can acquire it.

### Use Separate Cache Directories

For parallel scans with filesystem cache, isolate each process by specifying unique cache directories via the `--cache-dir` flag:

```bash
trivy image --cache-dir /tmp/trivy-cache-1 debian:11 &
trivy image --cache-dir /tmp/trivy-cache-2 debian:12 &

```

**Note**: This approach causes each instance to download and store its own copy of the vulnerability database, increasing network bandwidth usage and disk space consumption.

## Summary

- The **Trivy database lock error** stems from BoltDB's exclusive file lock in [`pkg/cache/fs.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/cache/fs.go), preventing concurrent filesystem cache access with the message "cache may be in use by another process"
- **Memory cache** (`--cache-backend memory`) eliminates locking issues for compatible commands by avoiding disk-based storage
- **Redis cache** provides a shared, persistent solution for server deployments and multiple concurrent instances
- **Process termination** or **directory isolation** (`--cache-dir`) resolves conflicts when filesystem cache is mandatory but concurrent access is required

## Frequently Asked Questions

### What is the root cause of the Trivy database lock error?

The error occurs because Trivy's filesystem cache implementation in [`pkg/cache/fs.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/cache/fs.go) uses BoltDB, which enforces an exclusive OS-level file lock to prevent data corruption. When a second Trivy process attempts to access the same cache directory while another holds the lock, the BoltDB driver returns a "cache may be in use by another process" error, as handled in [`pkg/commands/run.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/commands/run.go).

### Can I manually delete the lock file to fix the error?

No, BoltDB does not create a separate `.lock` file that can be deleted. The lock is maintained by the operating system kernel at the file descriptor level. You must either terminate the competing Trivy process or switch to a non-locking cache backend like memory or Redis.

### Which cache backend offers the best performance for CI/CD pipelines?

**Memory cache** provides the fastest performance because it avoids disk I/O entirely, making it ideal for ephemeral CI/CD runners. However, since it does not persist between runs, pipelines must download vulnerability data each time. For shared persistent caching across pipeline runs, **Redis cache** offers the best balance of performance and durability.

### Why doesn't the vulnerability database itself cause lock errors?

According to the Trivy source code and troubleshooting documentation, the vulnerability database files are always opened in **read-only mode**, which does not require exclusive file locking. Only the filesystem cache (used for scan results, layer metadata, and artifact information) requires write access and thus triggers BoltDB's exclusive lock mechanism.