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

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, 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, Trivy implements the filesystem cache using BoltDB, an embedded key-value store. According to BoltDB's documentation referenced in 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 and the error handling in 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:

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:

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:

ps aux | grep trivy
kill <process_id>

This releases the OS-level file lock in 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:

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, 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 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}