Skip to content

docs: improve guidance for cache lock errors in parallel runs #10176

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MenaceHecker wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: improve guidance for cache lock errors in parallel runs #10176

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
56fdae5
docs: improve guidance for cache lock errors in parallel runs
MenaceHecker Feb 9, 2026
06732b7
Promoted cache directory isolation as recommended fix for parallel runs
MenaceHecker Feb 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 16 additions & 11 deletions docs/guide/references/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,22 @@ These errors occur when:
- A previous Trivy process did not shut down cleanly
- Trivy server is running with filesystem cache and holding a lock on the cache

#### Recommended for parallel runs / CI

If you run multiple Trivy processes concurrently (for example, CI matrix jobs or background scans), ensure that each process uses a different filesystem cache directory to avoid sharing the same BoltDB lock.

For example:

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

Note:
- No `$RANDOM` anymore
- Explicitly references what already exists conceptually
- Frames this as **recommended**, not “new”


#### Solutions

**Solution 1: Use memory cache or Redis cache** (Recommended)
Expand Down Expand Up @@ -189,17 +205,6 @@ $ ps aux | grep trivy
$ kill [process_id]
```

**Solution 3: Use different cache directories**

If you must run multiple Trivy processes with filesystem cache, specify different cache directories for each process:

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

Note that each cache directory will download its own copy of the vulnerability database and other scan assets, which will increase network traffic and storage usage.

### Multiple Trivy servers

!!! error
Expand Down