{"record":{"id":"7c562cd25e3cf1ad","repo":"can1357/oh-my-pi","slug":"line-hint-linehintforinsertion-is-out-of-range","errorCode":null,"errorMessage":"Line hint ${lineHintForInsertion} is out of range for insertion in ${path} (line numbers start at 1)","messagePattern":"Line hint (.+?) is out of range for insertion in (.+?) \\(line numbers start at 1\\)","errorType":"validation","errorClass":"ApplyPatchError","httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/edit/modes/patch.ts","lineNumber":1181,"sourceCode":"\t\t\t\t} else {\n\t\t\t\t\tlineIndex = idx + 1;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tif (hunk.oldLines.length === 0) {\n\t\t\t// Pure addition - prefer changeContext position, then line hint, then end of file\n\t\t\tlet insertionIdx: number;\n\t\t\tif (hunk.changeContext !== undefined) {\n\t\t\t\t// changeContext was processed above; lineIndex is set to the context line or after it\n\t\t\t\tinsertionIdx = lineIndex;\n\t\t\t} else {\n\t\t\t\tconst lineHintForInsertion = hunk.oldStartLine ?? hunk.newStartLine;\n\t\t\t\tif (lineHintForInsertion !== undefined) {\n\t\t\t\t\t// Reject if line hint is out of range for insertion\n\t\t\t\t\t// Valid insertion points are 1 to (file length + 1) for 1-indexed hints\n\t\t\t\t\tif (lineHintForInsertion < 1) {\n\t\t\t\t\t\tthrow new ApplyPatchError(\n\t\t\t\t\t\t\t`Line hint ${lineHintForInsertion} is out of range for insertion in ${path} ` +\n\t\t\t\t\t\t\t\t`(line numbers start at 1)`,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\tif (lineHintForInsertion > originalLines.length + 1) {\n\t\t\t\t\t\tthrow new ApplyPatchError(\n\t\t\t\t\t\t\t`Line hint ${lineHintForInsertion} is out of range for insertion in ${path} ` +\n\t\t\t\t\t\t\t\t`(file has ${originalLines.length} lines)`,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\tinsertionIdx = Math.max(0, lineHintForInsertion - 1);\n\t\t\t\t} else {\n\t\t\t\t\tinsertionIdx =\n\t\t\t\t\t\toriginalLines.length > 0 && originalLines[originalLines.length - 1] === \"\"\n\t\t\t\t\t\t\t? originalLines.length - 1\n\t\t\t\t\t\t\t: originalLines.length;\n\t\t\t\t}\n\t\t\t}","sourceCodeStart":1163,"sourceCodeEnd":1199,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/edit/modes/patch.ts#L1163-L1199","documentation":"For a pure-insertion hunk (no removed lines) positioned by a line hint rather than a @@ anchor, the hint must fall in the valid 1-indexed insertion range. If oldStartLine ?? newStartLine is less than 1, the hint is invalid and an ApplyPatchError is thrown before any insertion occurs. Valid insertion points are 1 through file length + 1.","triggerScenarios":"An addition-only hunk with a header like `@@ -0` or negative start line that carries no changeContext, so the insertion-index branch validates lineHintForInsertion.","commonSituations":"Patch generators emitting 0-indexed coordinates for pure additions; hand-written diffs that treat the position before line 1 as line 0; template-generated insert blocks with unfilled hint fields.","solutions":["Set the hunk's start line hint to 1 or greater (1 inserts at the top of the file, length+1 at the end).","Remove the line hint so the insertion defaults to end-of-file.","Use a @@ changeContext anchor instead of a line hint to position the insertion.","Fix the generator that emits 0-indexed insertion coordinates."],"exampleFix":"// before\n@@ -0 +0,2 @@\n+new line\n\n// after\n@@ -1,0 +1,2 @@\n+new line","handlingStrategy":"validation","validationCode":"if (hunk.oldLines.length === 0 && lineHint !== undefined && lineHint < 1) {\n  // insertion hints are 1-indexed: 1 = top of file\n  lineHint = Math.max(1, lineHint);\n}","typeGuard":"function isValidInsertionHint(hint: number, fileLineCount: number): boolean {\n  return hint >= 1 && hint <= fileLineCount + 1;\n}","tryCatchPattern":"try {\n  applyPatch(patch);\n} catch (err) {\n  if (err instanceof ApplyPatchError && err.message.includes('out of range for insertion')) {\n    // clamp the hint to [1, lineCount + 1] and retry\n  } else throw err;\n}","preventionTips":["Remember insertion hints are 1-indexed; line 0 is never valid.","Clamp computed insertion positions before building the patch.","Prefer @@ anchors for insertions; use hints only when you know the exact index.","Omit the hint to append at end of file."],"tags":["patch","insertion","line-numbers","validation"],"backgroundTag":"patch-line-hint-out-of-range","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}