can1357/oh-my-pi · error · ToolError

memory_reference is required for read_memory

Error message

memory_reference is required for read_memory

What it means

The debug tool's read_memory action forwards a DAP (Debug Adapter Protocol) readMemory request to the active debug adapter session. The DAP protocol requires a memory_reference string identifying which memory region to read. This library throws a ToolError early, before contacting the adapter, when the caller omitted it. It is a fast-fail parameter validation guard, not a protocol failure.

Source

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

					throw new ToolError("instruction_count is required for disassemble");
				}
				const response = await dapSessionManager.disassemble(
					resolveDisassemblyReference(params.memory_reference),
					params.instruction_count,
					params.offset,
					params.instruction_offset,
					params.resolve_symbols,
					combinedSignal,
					timeoutSec * 1000,
				);
				details.snapshot = response.snapshot;
				details.disassembly = response.instructions;
				return result.text(formatDisassembly(response.instructions)).done();
			}
			case "read_memory": {
				requireCapability("supportsReadMemoryRequest", "memory reads");
				if (!params.memory_reference) {
					throw new ToolError("memory_reference is required for read_memory");
				}
				if (params.count === undefined) {
					throw new ToolError("count is required for read_memory");
				}
				const response = await dapSessionManager.readMemory(
					params.memory_reference,
					params.count,
					params.offset,
					combinedSignal,
					timeoutSec * 1000,
				);
				details.snapshot = response.snapshot;
				details.memoryAddress = response.address;
				details.memoryData = response.data;
				details.unreadableBytes = response.unreadableBytes;
				return result.text(formatMemoryRead(response.address, response.data, response.unreadableBytes)).done();
			}
			case "write_memory": {

View on GitHub (pinned to 9690622007)

Solutions

1. Obtain a valid memory_reference first: call read_memory only with a memoryReference returned by an earlier variables/scopes/stack_trace response.
2. Check the tool params use snake_case: memory_reference, count, offset — not DAP's camelCase memoryReference.
3. Ensure count is also supplied (it is separately required) and is a positive number.
4. Verify the active debug adapter actually supports memory reads (supportsReadMemoryRequest capability) — the capability check runs before this one and will surface its own error otherwise.

Example fix

// before
await debugTool.run({ action: "read_memory", count: 64 });
// after
await debugTool.run({ action: "read_memory", memory_reference: memoryRef, count: 64 });

if (typeof memoryRef !== "string" || memoryRef.length === 0) throw new Error("read_memory requires a memory_reference from a prior variables/scopes call");
if (typeof count !== "number" || count <= 0) throw new Error("read_memory requires a positive count");

function hasMemoryRef(p: { memory_reference?: string }): p is { memory_reference: string } {
  return typeof p.memory_reference === "string" && p.memory_reference.length > 0;
}

try {
  await debugTool.run({ action: "read_memory", memory_reference: ref, count: 256 });
} catch (err) {
  if (err instanceof ToolError && err.message.includes("memory_reference is required")) {
    // re-fetch a fresh memoryReference via stack_trace/variables, then retry
  } else throw err;
}

When it happens

Trigger: Invoking the debug tool with action="read_memory" while params.memory_reference is undefined, null, or an empty string. Typically happens when the caller never called stack_trace/variables/scopes first to obtain a memoryReference, or passed a wrong params key (e.g. memoryReference vs memory_reference).

Common situations: Agents or scripts composing tool calls from LLM output that omit the memory reference; hand-written automation copying a variable reference incorrectly; cases where the debug session was restarted and the previously captured memoryReference was lost; confusing camelCase DAP field names with the tool's snake_case parameter names.

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

• count is required for read_memory
• memory_reference is required for write_memory
• data is required for write_memory
• command is required for custom_request
• Debugger reported no threads.

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