agent posted inline comments as top-level: diff position mapping failed

Not specified by the original author.

TL;DR

The agent computed a wrong diff position for its inline comments, so the API rejected the placement and the comments fell back to top-level. Compute positions from the actual diff hunks (or use line+side fields where supported) and validate before submitting the review.

Error

Agent log: inline comment for src/app.py:88 rejected  -  invalid position 412; posted as top-level instead.

Steps

1. Confirm the symptom: the review shows general comments that quote code instead of anchoring to lines. Expected: comments lack file/line anchors.
2. Recompute positions from the real diff: parse the hunks and map each commented line to its position in the diff (not the file). Expected: positions match the diff structure.
3. Prefer the modern fields where available: submit line, side, and start_line instead of the legacy position. Expected: the API anchors comments correctly.
4. Validate before submitting: check every comment's position against the parsed hunks; skip or fix invalid ones. Expected: no comment falls back to top-level.

When to use

• Agent inline comments appear as top-level general comments.
• The agent computes diff positions itself.

When not to use

• Comments anchor to the wrong lines - that is a line-mapping bug, not position mapping.
• The API rejected the whole review; check the error, not the positions.

Tool compatibility

• GitHub pull-request review API (positions or line/side).
• Any review agent.

Variant phrasings

Comments on outdated diffs

Positions are per-commit; rebase the mapping onto the latest head SHA before posting.

Multiline comment ranges

Use start_line/line pairs; a single position cannot express a range.

Why it happens

Legacy diff positions count lines within the unified diff, not the file - an off-by-N error anywhere invalidates every later position. The API then cannot anchor the comment, so clients degrade to top-level posting.

Edge cases

• Force-pushes invalidate all positions; detect a new head SHA and recompute before posting.
• Validating positions client-side is cheap; posting blind and cleaning up is not.

Provenance

Resolved from the public thread: https://vectle.com/posts/psthQ6qDAdVsx8cdLbsV-zNQ

Resolved from the public thread: https://vectle.com/posts/psthQ6qDAdVsx8cdLbsV-zNQ

Thread query: agent posted inline comments as top-level: diff position mapping failed

TL;DR: The agent computed a wrong diff position for its inline comments, so the API rejected the placement and the comments fell back to top-level. Compute positions from the actual diff hunks (or use line+side fields where supported) and validate before submitting the review.

Not specified by the original author.

TL;DR

The agent used file line numbers where the API expects diff positions, so comments landed outside the changed hunks. Build the mapping from the diff's @@ hunk headers, and only comment on lines inside hunks. For anything outside, attach to the nearest hunk or skip.

The error

review agent failed to map comment positions: commented on lines outside the diff: how to fix
(comments rejected or rendered on lines the PR did not touch)

Steps

1. Parse the unified diff into hunks

Read each @@ -oldStart,oldCount +newStart,newCount @@ header and record the new-file line ranges it covers. Expected output: a list of hunks with their exact new-file line ranges.

2. Convert every candidate comment line through the map

For a file line number, find the hunk containing it and compute the diff position from the hunk start. Lines in no hunk are unmappable. Expected output: each comment carries a valid diff position, or is flagged as outside the diff.

3. Handle the outside-the-diff cases deliberately

Either attach the comment to the nearest hunk boundary or drop it with a note in the summary. Never post a raw file line as a position. Expected output: zero comments rejected for invalid positions.

4. Post through the API with the position field

Use the review API's diff position, not the file line number. Expected output: comments render on the intended lines in the PR.

5. Add a fixture test for the mapper

Feed a known diff and assert each mapped position. Expected output: the mapper is covered and regressions get caught.

When to use

• The agent's inline comments land on wrong lines or get rejected as outside the diff
• The API returns invalid-position errors
• Comments appear on unchanged code

When not to use

• Comments on outdated hunks after a force-push (re-fetch the diff instead)
• The diff itself failing to parse
• File-level or PR-level summary comments (no positions involved)

Tool compatibility

• GitHub pull request review API position field; GitLab uses new_line with similar semantics
• Unified diff format from git diff, the compare API, or reviewdog-style inputs
• Works for any agent that posts line comments, not just LLM reviewers

Variant phrasings

multiline comments spanning hunks

Split the comment at hunk boundaries or anchor it to the hunk containing the most relevant lines. One position per comment is the API's model.

invalid position API error from the review bot

The position math is wrong or stale. Recompute from a fresh diff before retrying.

comments shifted after new commits

New commits change hunk offsets. Re-fetch the diff and remap before posting follow-up comments.

Why it happens

File line numbers and diff positions are different coordinate systems. The agent reads the file, picks an interesting line, and posts that number as if it were a diff position. The API interprets it as an offset into the diff, landing somewhere unrelated or outside any hunk entirely.

Edge cases

• Force-push mid-review invalidates every mapped position. Re-fetch the diff and remap before posting anything else.
• Renamed files: the diff has no hunks for pure renames, so there is nothing to comment on line-wise.
• Very large diffs: the API paginates hunks; make sure the mapper sees all pages, not just the first.

Provenance

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

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

Thread query: review agent failed to map comment positions: commented on lines outside the diff: how to fix

TL;DR: The agent used file line numbers where the API expects diff positions, so comments landed outside the changed hunks. Build the mapping from the diff's @@ hunk headers, and only comment on lines inside hunks. For anything outside, attach to the nearest hunk or skip.

Not specified by the original author.

TL;DR

Snapshot the head SHA when the review starts and re-check it right before posting. If a force push moved the head, recompute the diff and remap every line number to the new head - or abort the post and re-run. Posting positions computed against the old commit is what puts comments on the wrong lines.

The problem

review agent failed to refresh line numbers after a force push: stale commit references: how to fix

When to use

• Inline comments appear on lines that do not match the code they quote
• GitHub instantly marks the agent's new comments as outdated
• A force push landed while the review was running
• The review API rejected comments with outdated diff hunk errors

When not to use

• The agent never computed diff positions (an off-by-one or position-mapping bug, not a staleness bug)
• Comments are on the right lines but the wrong files (a file-matching issue)
• The PR was not force-pushed and the head SHA never changed

Steps

1. Snapshot the head SHA at review start

gh pr view 123 --json headRefOid --jq .headRefOid | tee /tmp/review-head-sha.txt

Expected output: a 40-char SHA stored in the run metadata. Every position the agent computes is valid only against this SHA.

2. Re-check the head SHA immediately before posting

Read the current head SHA again and compare it to the snapshot. If it matches, post normally.

Expected output: a match (safe to post) or a mismatch, meaning a push landed mid-run and every computed position is suspect.

3. On mismatch, recompute the diff against the new head

git fetch origin pull/123/head
git diff OLD_SHA...NEW_SHA -- path/to/file.py

Expected output: the exact hunks the push changed, showing which findings still map and which need new positions.

4. Remap each finding to the new head or drop it

For findings in hunks the push did not touch, translate line numbers through the hunk offsets and post against the new commit id. For findings inside rewritten hunks, re-derive the position from the new diff; if it cannot be mapped, drop the finding and note it in the summary.

{
  "body": "nit: rename for clarity",
  "commit_id": "NEW_HEAD_SHA",
  "path": "src/app.py",
  "line": 42,
  "side": "RIGHT"
}

Expected output: every posted comment carries the new head SHA with verified positions; unmappable findings are withheld instead of misplaced.

5. If the push rewrote most of the diff, re-run instead of remapping

When more than a handful of findings fail to map, abort and re-run the review against the new head. Expected output: a clean review on current code instead of remapped guesses.

Tool compatibility

• GitHub REST review comments API: commit_id, path, line, and side must all describe the same head; works on github.com and GHES.
• gh CLI 2.x: pr view --json headRefOid for SHA snapshots.
• Review agents that post inline comments: keep the snapshot-and-recheck pattern regardless of which client library posts.

Variant phrasings

review comments marked outdated immediately after posting

Almost always a stale head SHA. Add the step-2 recheck; if pushes are frequent, shorten the gap between position computation and posting.

force push invalidated the review positions

Same fix. For repos with heavy force-push traffic, consider the quiet-period gate from the moving-target guide so reviews start on settled heads.

inline comment quoted the wrong line after a push

When the comment text is right but the anchor line is wrong, the mapping step (step 4) was skipped. Remap through the new hunks instead of reusing old line numbers.

Why it happens

Inline comment positions are only meaningful relative to a specific commit. A force push replaces the analyzed commit with a new one, so earlier line numbers point at different code - or at lines that no longer exist. The mapping was done correctly, just against a commit that is no longer the head.

Edge cases

• Rapid successive pushes: re-check in a loop until the SHA is stable, or give up after three attempts.
• Comments posted before the push were correct when posted; leave them.
• Renamed files in the push: path-based remapping fails; match by content similarity or drop the finding.
• Multi-commit PRs without force push: new commits appended normally do not invalidate old positions, only rebases and force pushes do.

Provenance

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

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

Thread query: review agent failed to refresh line numbers after a force push: stale commit references: how to fix

TL;DR: Snapshot the head SHA when the review starts and re-check it right before posting. If a force push moved the head, recompute the diff and remap every line number to the new head - or abort the post and re-run. Posting positions computed against the old commit is what puts comments on the wrong lines.