can1357/oh-my-pi · error · ToolError

instruction_reference is required for set_instruction_breakp

Error message

instruction_reference is required for set_instruction_breakpoint

What it means

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.

Source

Thrown at packages/coding-agent/src/tools/debug.ts:845

				}
				if (!params.file || params.line === undefined) {
					throw new ToolError("remove_breakpoint requires file+line or function");
				}
				const file = resolveToCwd(params.file, this.session.cwd);
				const response = await dapSessionManager.removeBreakpoint(
					file,
					params.line,
					combinedSignal,
					timeoutSec * 1000,
				);
				details.snapshot = response.snapshot;
				details.breakpoints = response.breakpoints;
				return result.text(formatBreakpoints(response.sourcePath, response.breakpoints)).done();
			}
			case "set_instruction_breakpoint": {
				requireCapability("supportsInstructionBreakpoints", "instruction breakpoints");
				if (!params.instruction_reference) {
					throw new ToolError("instruction_reference is required for set_instruction_breakpoint");
				}
				const response = await dapSessionManager.setInstructionBreakpoint(
					params.instruction_reference,
					params.offset,
					params.condition,
					params.hit_condition,
					combinedSignal,
					timeoutSec * 1000,
				);
				details.snapshot = response.snapshot;
				details.instructionBreakpoints = response.breakpoints;
				return result.text(formatInstructionBreakpoints(response.breakpoints)).done();
			}
			case "remove_instruction_breakpoint": {
				requireCapability("supportsInstructionBreakpoints", "instruction breakpoints");
				if (!params.instruction_reference) {
					throw new ToolError("instruction_reference is required for remove_instruction_breakpoint");
				}

View on GitHub (pinned to 9690622007)

Solutions

1. Pass the instruction_reference string (typically from a prior disassemble call's instructionAddress)
2. Verify you intended an instruction breakpoint, not a source breakpoint (use set_breakpoint for file+line)
3. Confirm the active debug adapter supports instruction breakpoints (capability check runs before this error)

Example fix

// before
await debugTool.run({ action: 'set_instruction_breakpoint', offset: 4 });
// after
await debugTool.run({ action: 'set_instruction_breakpoint', instruction_reference: '0x00400a1b' });

if (typeof params.instruction_reference !== 'string' || params.instruction_reference.length === 0) {
  throw new Error('set_instruction_breakpoint needs instruction_reference');
}

function hasInstructionReference(p) {
  return typeof p === 'object' && p !== null
    && typeof (p as { instruction_reference?: unknown }).instruction_reference === 'string'
    && (p as { instruction_reference: string }).instruction_reference.length > 0;
}

try {
  await debugTool.run({ action: 'set_instruction_breakpoint', ...params });
} catch (err) {
  if (err instanceof ToolError && err.message.includes('instruction_reference is required')) {
    // obtain an address via disassemble, then retry
  } else throw err;
}

When it happens

Trigger: Calling action=set_instruction_breakpoint without instruction_reference, or with an empty string.

Common situations: 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.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• instruction_reference is required for remove_instruction_bre
• set_breakpoint requires file+line or function
• remove_breakpoint requires file+line or function
• name is required for data_breakpoint_info
• data_id is required for set_data_breakpoint

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/7fb08fe4f6acdf5d. Report an issue: GitHub.