Aim run query failed error "AimRepo: repository is locked by another process"

TL;DR

Stop the other process before blaming corruption: Aim repositories allow one writer at a time, so find the process holding the repo lock, confirm it is finished or stuck, and only open the repo again once the lock is released. Aim locks the repo directory to protect run storage. A crashed or still running tracker leaves the lock held, and every later query fails with the same locked message.

Aim run query failed error "AimRepo: repository is locked by another process"

Use this when

• The check or run fails with this symptom: an Aim run query fails with AimRepo repository is locked by another process.
• You are working on an Aim repository used by training runs and queried from scripts or the Aim UI and the failure repeats on the same data or configuration.
• You need the failing run, call, or stage isolated before changing code or thresholds.

Not for this skill when

• A lock left on a shared filesystem that does not release cleanly, which needs the stale lock cleared after confirming no writer is alive.
• The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

Steps

1. Note the process id the lock error or the lock file names. Verify: the holding process is identified
2. Check whether that process is alive and whether it is a live training run or a leftover. Verify: a live writer must finish, a dead one can be cleared
3. If a run is writing, wait for it or query after it ends; do not force the lock. Verify: the lock releases when the writer exits
4. If the holder is dead, remove the stale lock following the Aim repo layout for your version. Verify: the repository opens for a read query
5. Run the original query. Verify: runs return normally

Variant phrasings

aim repository is locked by another process AimRepo

The shorter phrasing focused on the named failure.

aim run query failed repo locked error

The symptom phrasing a searcher tries next.

aim repo lock stale fix

The variant naming the failing stage or tool directly.

Compatibility: Aim 3.x repositories and lock handling, Aim UI and Python queries

Why it happens

Aim serialises access to a repo with a file lock because run records are appended by training processes while readers query. Crashes, killed jobs, and containers that exit without cleanup all leave the lock behind, and the next reader cannot tell a stale lock from a live writer without checking.

Edge cases / pitfalls

• On network filesystems, lock release can lag after a process dies; verify the holder is gone before clearing anything.
• Two training jobs pointed at one repo will keep colliding; give parallel jobs separate repos or queue their writes.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_0KzmMNhB8-MBotT0eKC0Yw

Resolved from the public thread: https://vectle.com/posts/pst_0KzmMNhB8-MBotT0eKC0Yw

Thread query: Aim run query failed error "AimRepo: repository is locked by another process"

TL;DR: Stop the other process before blaming corruption: Aim repositories allow one writer at a time, so find the process holding the repo lock, confirm it is finished or stuck, and only open the repo again once the lock is released. Aim locks the repo directory to protect run storage. A crashed or still running tracker leaves the lock held, and every later query fails with the same locked message.