reviewdog: error: fail to parse diff: unexpected hunk header

TL;DR

Feed reviewdog a clean unified diff or it chokes. The error means the diff piped into reviewdog has malformed or non-standard hunks. Re-generate the diff with plain git diff flags, strip binary files and external diff output, and the error goes away. It is a diff-format problem, not a reviewdog config problem.

The query

reviewdog: error: fail to parse diff: unexpected hunk header

Use this when

• A CI job running reviewdog dies with "fail to parse diff"
• reviewdog works on most PRs but fails on ones with renames, merges, or binary files
• You piped a custom diff command into reviewdog and it errored

Not for

• reviewdog "no filter matched for changed files"
• reviewdog annotation posting errors (permissions, auth)
• Writing new reviewdog errorformat rules

Steps

1. Dump the exact diff your pipeline feeds reviewdog

Run the same diff command CI uses and save it:

git diff origin/main...HEAD > /tmp/pr.diff
head -c 2000 /tmp/pr.diff

Expected output: a normal unified diff starting with diff --git lines and @@ -a,b +c,d @@ hunk headers.

2. Hunt for non-standard hunks

grep -n "^diff --git" /tmp/pr.diff | head
grep -c "^@@" /tmp/pr.diff

Suspects: GIT binary patch sections, rename from/to pairs with no hunks, combined merge diffs, or color codes. Expected output: you can see which file sections lack a proper @@ header.

3. Regenerate with reviewdog-friendly flags

git diff --no-color --no-ext-diff -U3 origin/main...HEAD > /tmp/pr.diff

Expected output: no color codes, no external diff driver output, standard hunks only.

4. Exclude binary files from the reviewed diff

git diff --no-color -U3 origin/main...HEAD -- . ":!*.png" ":!*.jpg" ":!*.pdf" ":!*.woff2" > /tmp/pr.diff

Expected output: binary patch sections gone from the diff.

5. Re-run the reviewdog step against the cleaned diff

Point reviewdog at the cleaned file (or bake the flags from steps 3-4 into your diff-generation step) and re-run CI.

Expected output: reviewdog exits 0 and posts annotations instead of the parse error.

Variant phrasings

reviewdog fail to parse diff on PR

Same fix. If the diff comes from the GitHub API instead of git, fetch the raw unified diff with the diff media type so reviewdog gets clean hunks.

unexpected hunk header from reviewdog in GitHub Actions

Check the diff-generation step first. A shallow fetch or a missing base ref produces truncated diffs. Fetch enough history or pass the base SHA explicitly.

Why it happens

reviewdog parses the diff itself to map linter output onto file and line positions. Its parser expects strict unified format. Binary patches, merge combined diffs, external diff driver output, and colorized diffs all break that assumption, and it reports the first unparseable hunk header it hits.

Edge cases

• Renamed files: reviewdog handles rename hunks, but only when similarity detection stayed intact. Renames detected as delete-plus-add on some versions confuse the parser.
• Huge diffs: parse errors can mask a timeout. Check stderr around the error for context lines.
• Version skew: older reviewdog releases had a stricter parser. Pin a recent version in CI before debugging the diff itself.

Provenance

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