What causes "Absolute paths are not allowed in omp:// URLs" in can1357/oh-my-pi?

Use the relative doc filename only, e.g. omp://docs/cli.md instead of omp:///home/user/docs/cli.md.

Absolute paths are not allowed in omp:// URLs

Error message

Absolute paths are not allowed in omp:// URLs

What it means

omp:// URLs can only name bundled doc files, not filesystem paths. #readDoc rejects any filename where path.isAbsolute() is true, e.g. omp:///etc/passwd or omp://C:/x, before any lookup happens.

Source

Thrown at packages/coding-agent/src/internal-urls/omp-protocol.ts:60

		if (filenames.length === 0) {
			throw new Error("No documentation files found");
		}

		const listing = filenames.map(f => `- [${f}](omp://${f})`).join("\n");
		const content = `# Documentation\n\n${filenames.length} files available:\n\n${listing}\n`;

		return {
			url: url.href,
			content,
			contentType: "text/markdown",
			size: Buffer.byteLength(content, "utf-8"),
		};
	}

	async #readDoc(filename: string, url: InternalUrl): Promise<InternalResource> {
		// Validate: no traversal, no absolute paths
		if (path.isAbsolute(filename)) {
			throw new Error("Absolute paths are not allowed in omp:// URLs");
		}

		const normalized = path.posix.normalize(filename.replaceAll("\\", "/"));
		if (normalized === ".." || normalized.startsWith("../") || normalized.includes("/../")) {
			throw new Error("Path traversal (..) is not allowed in omp:// URLs");
		}

		const docPath =
			normalized === "docs" ? "" : normalized.startsWith("docs/") ? normalized.slice("docs/".length) : normalized;
		if (!docPath) {
			return this.#listDocs(url);
		}

		const content = await getEmbeddedDoc(docPath);
		if (content === undefined) {
			const lookup = docPath.replace(/\.md$/, "");
			const suggestions = getDocFilenames()
				.filter(f => f.includes(lookup) || lookup.includes(f.replace(/\.md$/, "")))

View on GitHub (pinned to 9690622007)

Solutions

Use the relative doc filename only, e.g. omp://docs/cli.md instead of omp:///home/user/docs/cli.md.
Strip the leading slash or drive prefix from the path before building the URL.
If you need filesystem access, use file:// paths or the read tool, not omp://.

Example fix

// before
router.resolve(`omp://${absolutePath}`);
// after
const rel = path.relative(docsRoot, absolutePath);
router.resolve(`omp://${rel}`);

Defensive patterns

Strategy: validation

Validate before calling

import * as path from 'node:path';
const docName = pathname.replace(/^\//, '');
if (path.isAbsolute(docName) || /^[a-zA-Z]:/.test(docName)) throw new Error('omp:// expects a relative doc name');

Type guard

const isValidDocName = (s: string): boolean =>
  !path.isAbsolute(s) && !/^[a-zA-Z]:/.test(s) && !s.includes('\\');

Try / catch

try {
  return await router.resolve(url);
} catch (err) {
  if (err instanceof Error && err.message.includes('Absolute paths are not allowed')) throw new Error(`use a relative doc name, got: ${url}`);
  throw err;
}

Prevention

Always build omp:// URLs from relative doc names only.
Never embed filesystem paths or user-supplied absolute paths into omp:// URLs.
Use file:// or the read tool when the target is an actual path.

When it happens

Trigger: Resolving an omp:// URL whose path component is absolute — starts with '/' or a Windows drive letter — instead of a relative doc filename such as 'docs/cli.md'.

Common situations: Treating omp:// like file://; templating a full path into an omp URL; accidentally prefixing a doc name with '/'.

Related errors

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