## TL;DR
Release the repo lock before fetching: the agent failed to parse Aim query results because the underlying fetch hit the locked repo, so coordinate reads with the writing process, or read from a snapshot copy of the repo for analysis. The parse failure is downstream of a storage failure. Aim returned an error or a partial result, and the agent parser reported the symptom it could see.

```text
agent failed to parse Aim query results after repo lock error failed to fetch runs
```

## Use this when
- The check or run fails with this symptom: an agent fails to parse Aim query results after a repo lock error and cannot fetch runs.
- You are working on an agent workflow analysing Aim runs while training jobs write to the same repo 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 repo with no writer that still reports locked, which is the stale lock case needing the lock cleared first.
- The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

## Steps
1. Reproduce the fetch directly and read the raw response. Verify: the response is a lock error, not run data
2. Identify the process writing to the repo and its expected finish. Verify: the read can be scheduled after the write window
3. For repeated analysis, copy or snapshot the repo and query the copy. Verify: analysis reads succeed while training continues
4. Change the agent to check fetch success and content type before parsing. Verify: a lock error is reported as a lock error
5. Rerun the analysis. Verify: run results parse and summarise normally

## Variant phrasings
### agent parse aim query results repo lock failed fetch
The shorter phrasing focused on the named failure.
### aim repo lock agent fetch runs error
The symptom phrasing a searcher tries next.
### aim locked repo agent read fix
The variant naming the failing stage or tool directly.

Compatibility: Aim repository locking, agent analysis workflows over live experiment repos

## Why it happens
Agents chain tools assuming each step returns what the next expects. A lock error returned where run data was expected flows into a parser, and the parser error is what gets reported, sending debugging toward file formats instead of the simple contention underneath.

## Edge cases / pitfalls
- Validate every fetch by status and shape before parsing; parsers should never be the first place an upstream error is described.
- Read replicas or snapshots are the durable answer for repos under continuous write load.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_h7FDhs5Co9ZN7zV0_4vGHQ