Fixing Context Mismatch Errors

When Patches Fail: Context Mismatch

The most common reason a patch fails to apply is a context mismatch — the context lines in the patch do not match the actual lines in the file at the expected position.

Common Causes

1. File was modified since the patch was created — other changes shifted lines
2. Whitespace differences — tabs vs spaces, trailing whitespace, different line endings
3. Encoding differences — the file was re-encoded (e.g., UTF-8 BOM added)
4. Wrong file version — the patch was created against a different version

How Fuzzy Matching Helps

The Diff Patch Applier tries fuzzy matching before reporting failure:

Expected position: line 50
Search range: lines 47-53 (±3 lines)
Best match: line 52 (all context lines match)
Result: hunk applied with offset +2

Debugging Steps

1. Check the hunk list — see which hunks succeeded and failed
2. Compare context lines — verify the prefixed lines match your file
3. Check whitespace — use a diff viewer to compare whitespace
4. Try wider context — if the file has changed a lot, the ±3 line fuzzy range may not be enough

Manual Fix Options

If a hunk fails:

1. Edit the patch — update context lines to match the current file
2. Adjust line numbers — update the @@ header to the correct position
3. Apply manually — use the diff preview to see what should change and edit by hand
4. Regenerate — if you have both versions, use Generate Diff mode to create a fresh patch

Prevention

To minimize context mismatches:

• Apply patches promptly before the file diverges further
• Use larger context (e.g., diff -U5) when creating patches for files that change frequently
• Keep patches small and focused on a single logical change