{"record":{"id":"7fb08fe4f6acdf5d","repo":"can1357/oh-my-pi","slug":"instruction-reference-is-required-for-set-instruct","errorCode":null,"errorMessage":"instruction_reference is required for set_instruction_breakpoint","messagePattern":"instruction_reference is required for set_instruction_breakpoint","errorType":"validation","errorClass":"ToolError","httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/tools/debug.ts","lineNumber":845,"sourceCode":"\t\t\t\t}\n\t\t\t\tif (!params.file || params.line === undefined) {\n\t\t\t\t\tthrow new ToolError(\"remove_breakpoint requires file+line or function\");\n\t\t\t\t}\n\t\t\t\tconst file = resolveToCwd(params.file, this.session.cwd);\n\t\t\t\tconst response = await dapSessionManager.removeBreakpoint(\n\t\t\t\t\tfile,\n\t\t\t\t\tparams.line,\n\t\t\t\t\tcombinedSignal,\n\t\t\t\t\ttimeoutSec * 1000,\n\t\t\t\t);\n\t\t\t\tdetails.snapshot = response.snapshot;\n\t\t\t\tdetails.breakpoints = response.breakpoints;\n\t\t\t\treturn result.text(formatBreakpoints(response.sourcePath, response.breakpoints)).done();\n\t\t\t}\n\t\t\tcase \"set_instruction_breakpoint\": {\n\t\t\t\trequireCapability(\"supportsInstructionBreakpoints\", \"instruction breakpoints\");\n\t\t\t\tif (!params.instruction_reference) {\n\t\t\t\t\tthrow new ToolError(\"instruction_reference is required for set_instruction_breakpoint\");\n\t\t\t\t}\n\t\t\t\tconst response = await dapSessionManager.setInstructionBreakpoint(\n\t\t\t\t\tparams.instruction_reference,\n\t\t\t\t\tparams.offset,\n\t\t\t\t\tparams.condition,\n\t\t\t\t\tparams.hit_condition,\n\t\t\t\t\tcombinedSignal,\n\t\t\t\t\ttimeoutSec * 1000,\n\t\t\t\t);\n\t\t\t\tdetails.snapshot = response.snapshot;\n\t\t\t\tdetails.instructionBreakpoints = response.breakpoints;\n\t\t\t\treturn result.text(formatInstructionBreakpoints(response.breakpoints)).done();\n\t\t\t}\n\t\t\tcase \"remove_instruction_breakpoint\": {\n\t\t\t\trequireCapability(\"supportsInstructionBreakpoints\", \"instruction breakpoints\");\n\t\t\t\tif (!params.instruction_reference) {\n\t\t\t\t\tthrow new ToolError(\"instruction_reference is required for remove_instruction_breakpoint\");\n\t\t\t\t}","sourceCodeStart":827,"sourceCodeEnd":863,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/tools/debug.ts#L827-L863","documentation":"The set_instruction_breakpoint action throws this ToolError when params.instruction_reference is absent. Instruction breakpoints operate on CPU instruction addresses, not source lines, so an address/reference string is mandatory. The tool also requires the debug adapter to declare supportsInstructionBreakpoints capability first.","triggerScenarios":"Calling action=set_instruction_breakpoint without instruction_reference, or with an empty string.","commonSituations":"Caller confuses source breakpoints with instruction breakpoints and passes file/line only; instruction_reference not copied from a prior disassemble result; adapter supports capability but caller builds params dynamically and drops the field.","solutions":["Pass the instruction_reference string (typically from a prior disassemble call's instructionAddress)","Verify you intended an instruction breakpoint, not a source breakpoint (use set_breakpoint for file+line)","Confirm the active debug adapter supports instruction breakpoints (capability check runs before this error)"],"exampleFix":"// before\nawait debugTool.run({ action: 'set_instruction_breakpoint', offset: 4 });\n// after\nawait debugTool.run({ action: 'set_instruction_breakpoint', instruction_reference: '0x00400a1b' });","handlingStrategy":"validation","validationCode":"if (typeof params.instruction_reference !== 'string' || params.instruction_reference.length === 0) {\n  throw new Error('set_instruction_breakpoint needs instruction_reference');\n}","typeGuard":"function hasInstructionReference(p) {\n  return typeof p === 'object' && p !== null\n    && typeof (p as { instruction_reference?: unknown }).instruction_reference === 'string'\n    && (p as { instruction_reference: string }).instruction_reference.length > 0;\n}","tryCatchPattern":"try {\n  await debugTool.run({ action: 'set_instruction_breakpoint', ...params });\n} catch (err) {\n  if (err instanceof ToolError && err.message.includes('instruction_reference is required')) {\n    // obtain an address via disassemble, then retry\n  } else throw err;\n}","preventionTips":["Copy instruction_reference directly from a disassemble result's instructionAddress","Do not substitute file/line or offset for the address reference","Confirm the adapter advertises supportsInstructionBreakpoints before building these params"],"tags":["debug","dap","parameter-validation","instruction-breakpoint"],"backgroundTag":"missing-required-parameter","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}