can1357/oh-my-pi · error

Unknown subagent or session file unavailable: ${selector.sub

Error message

Unknown subagent or session file unavailable: ${selector.subagentId}

What it means

resolveSessionFile maps a get_subagent_messages selector to a session file on disk. When a subagentId is given, it is looked up first in the live subagent snapshots, then in the transcript's subagent-id-to-session-file index; if neither has the id (or the recorded file is absent), the resolver throws 'Unknown subagent or session file unavailable'.

Source

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

			progress,
		});
		if (this.#subscriptionLevel !== "off") {
			this.#output({ type: "subagent_progress", payload });
		}
	}

	handleEvent(payload: SubagentEventPayload): void {
		if (this.#staleSubagentIds.has(payload.id)) return;
		if (this.#subscriptionLevel !== "events") return;
		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

1. Use the subagentId exactly as returned when the subagent was spawned; list current subagents to confirm the ID.
2. If the session was restarted, resolve via the sessionFile path directly instead of the old subagentId.
3. Retry only after confirming the subagent has started and registered; otherwise treat as a permanent unknown-ID error.

Example fix

// before
const file = subagents.resolveSessionFile({ subagentId: oldId }); // oldId from previous run
// after
const file = subagents.resolveSessionFile({ sessionFile: knownSessionPath });

// confirm the id exists in the current session's subagent list before querying
const known = await rpc.listSubagents();
if (!known.some(s => s.id === selector.subagentId)) throw new Error(`subagent ${selector.subagentId} not in this session`);

try {
  const file = subagents.resolveSessionFile({ subagentId });
} catch (err) {
  if (err instanceof Error && err.message.startsWith("Unknown subagent or session file unavailable")) {
    // fall back to sessionFile-based lookup or report unknown id
  } else throw err;
}

When it happens

Trigger: Requesting subagent messages with a subagentId that was never spawned in this session, that has already been evicted from the registry and has no transcript mapping, or that belongs to a different session.

Common situations: A host caches subagent IDs from a previous run and queries them after a restart; a typo'd or stale ID from an external tool; querying before the subagent has registered its session file.

Related errors

• rpc chunk sequence interrupted
• rpc chunk sequence must start at index 0
• stale_cursor
• Unknown subagent session file
• get_subagent_messages requires subagentId or sessionFile

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