can1357/oh-my-pi · error · ToolError

Cannot resolve local:// URL in bash command: local protocol

Error message

Cannot resolve local:// URL in bash command: local protocol options are unavailable for this session.

What it means

local:// URLs can only be resolved when the session supplied LocalProtocolOptions (the mapping that turns a local:// resource into a concrete path). If resolveInternalUrlToPath is invoked without localOptions — the session doesn't support the local protocol — the tool throws immediately instead of guessing a path.

Source

Thrown at packages/coding-agent/src/tools/bash-skill-urls.ts:284

	if (!scheme) {
		throw new ToolError(`Unsupported internal URL in bash command: ${url}`);
	}

	if (scheme === "skill") {
		return resolveSkillUrlToPath(url, skills);
	}

	if (scheme === "attachment") {
		const attachment = attachments.find(entry => entry.uri === url);
		if (!attachment) {
			throw new ToolError(`Unknown attachment URL in bash command: ${url}`);
		}
		return path.resolve(attachment.sourcePath);
	}

	if (scheme === "local") {
		if (!localOptions) {
			throw new ToolError(
				"Cannot resolve local:// URL in bash command: local protocol options are unavailable for this session.",
			);
		}
		const resolvedLocalPath = resolveLocalUrlToPath(url, localOptions);
		if (ensureLocalParentDirs) {
			await fs.mkdir(path.dirname(resolvedLocalPath), { recursive: true });
		}
		return resolvedLocalPath;
	}

	if (!internalRouter?.canHandle(url)) {
		throw new ToolError(
			`Cannot resolve ${scheme}:// URL in bash command: ${url}\n` +
				"Internal URL router is unavailable for this protocol in the current session.",
		);
	}

	let resource: InternalResource;

View on GitHub (pinned to 9690622007)

Solutions

Enable/configure local protocol options for the session so local:// URLs are resolvable.
Rewrite the command to use a normal filesystem path instead of a local:// URL.
Use a different supported scheme (skill://, attachment://) that is available in this session.
When embedding the tool programmatically, pass valid LocalProtocolOptions to the bash tool invocation.

Defensive patterns

Strategy: fallback

Validate before calling

if (url.startsWith('local://') && !sessionSupportsLocalProtocol) return plainFilesystemPathInstead;

Try / catch

try { await expandInternalUrls(cmd, ctx); } catch (e) { if (e instanceof ToolError && e.message.includes('local://')) { /* rewrite command with a direct path or enable local protocol */ } else throw e; }

Prevention

Only use local:// URLs in sessions configured with local protocol options.
Configure LocalProtocolOptions when embedding the bash tool if commands may contain local:// URIs.
Default to ordinary paths in generated bash commands.

When it happens

Trigger: A bash command contains a local:// URL but the BashTool/session was constructed without local protocol options (localOptions undefined), e.g. remote sessions, sessions with local protocol disabled, or tests calling expandInternalUrls without wiring LocalProtocolOptions.

Common situations: Using local:// URIs in an environment (remote host, restricted session, SDK embedding) where the local protocol isn't configured; forgetting to pass local protocol options when invoking the bash tool programmatically.

Related errors

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