get_subagent_messages requires subagentId or sessionFile

Error message

get_subagent_messages requires subagentId or sessionFile

What it means

resolveSessionFile requires the selector to identify a transcript somehow: either subagentId or sessionFile. If neither field is provided (both undefined/empty), it throws 'get_subagent_messages requires subagentId or sessionFile'. This is a required-argument guard on the get_subagent_messages RPC.

Source

Thrown at packages/coding-agent/src/modes/rpc/rpc-subagents.ts:263

		this.#output({ type: "subagent_event", payload } satisfies RpcSubagentEventFrame);
	}

	resolveSessionFile(selector: RpcSubagentTranscriptSelector): string {
		if (selector.subagentId) {
			const snapshot = this.#subagents.get(selector.subagentId);
			const sessionFile = snapshot?.sessionFile ?? this.#transcriptSessionFilesBySubagentId.get(selector.subagentId);
			if (!sessionFile) {
				throw new Error(`Unknown subagent or session file unavailable: ${selector.subagentId}`);
			}
			return sessionFile;
		}

		if (selector.sessionFile) {
			if (this.#hasTranscriptSessionFile(selector.sessionFile)) return selector.sessionFile;
			throw new Error("Unknown subagent session file");
		}

		throw new Error("get_subagent_messages requires subagentId or sessionFile");
	}
}

View on GitHub (pinned to 9690622007)

Solutions

Always populate subagentId (preferred) or sessionFile in the selector before calling.
In dynamic callers, throw or skip the request client-side when neither field resolves.
Check field names — a typo like 'subagent_id' leaves the real field undefined.

Example fix

// before
await rpc.getSubagentMessages({});
// after
await rpc.getSubagentMessages({ subagentId: subagentId });

Defensive patterns

Strategy: validation

Validate before calling

if (!selector.subagentId && !selector.sessionFile) {
  throw new Error("get_subagent_messages requires subagentId or sessionFile");
}

Type guard

function isResolvableSelector(s: RpcSubagentTranscriptSelector): boolean {
  return Boolean(s.subagentId || s.sessionFile);
}

Try / catch

try {
  const file = subagents.resolveSessionFile(selector);
} catch (err) {
  if (err instanceof Error && /requires subagentId or sessionFile/.test(err.message)) {
    // skip request or prompt caller for a selector
  } else throw err;
}

Prevention

Type the selector so at least one of subagentId/sessionFile is required (union type).
Check field spelling (subagentId vs subagent_id) in dynamic callers.
Fail fast client-side when a dynamic selector resolves to an empty object.

When it happens

Trigger: Calling get_subagent_messages with an empty selector object {}, or with a selector whose subagentId and sessionFile are both undefined/null/empty strings.

Common situations: Generic host code that builds the selector dynamically from optional fields and forwards an empty object when neither is available; clients omitting fields because they assumed defaults.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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