garrytan/gstack · error · Error

Unsupported file URL host: ${segment}. Use file:///<absolute

Error message

Unsupported file URL host: ${segment}. Use file:///<absolute-path> for local files (network/UNC paths are not supported).

What it means

Thrown by normalizeFileUrl when the segment after `file://` looks like a host rather than a simple path name — anything containing `.`, `:`, `\`, `%`, or starting with `[`. The library does not support network/UNC/file-share URLs and refuses them rather than silently treating them as cwd-relative.

Source

Thrown at browse/src/url-validation.ts:206

    return pathToFileURL(absPath).href + trailing;
  }

  // localhost host explicitly allowed: file://localhost/<abs> (pass through to standard parser).
  if (afterDoubleSlash.toLowerCase().startsWith('localhost/')) {
    return pathPart + trailing;
  }

  // Ambiguous: file://<segment>/<rest> — treat as cwd-relative ONLY if <segment> is a
  // simple path name (no dots, no colons, no backslashes, no percent-encoding, no
  // IPv6 brackets, no Windows drive letter pattern).
  const firstSlash = afterDoubleSlash.indexOf('/');
  const segment = firstSlash === -1 ? afterDoubleSlash : afterDoubleSlash.slice(0, firstSlash);

  // Reject host-like segments: dotted names (docs.v1), IPs (127.0.0.1), IPv6 ([::1]),
  // drive letters (C:), percent-encoded, or backslash paths.
  const looksLikeHost = /[.:\\%]/.test(segment) || segment.startsWith('[');
  if (looksLikeHost) {
    throw new Error(
      `Unsupported file URL host: ${segment}. Use file:///<absolute-path> for local files (network/UNC paths are not supported).`
    );
  }

  // Simple-segment cwd-relative: file://docs/page.html → cwd/docs/page.html
  const absPath = path.resolve(process.cwd(), afterDoubleSlash);
  return pathToFileURL(absPath).href + trailing;
}

/**
 * Validate a navigation URL and return a normalized version suitable for page.goto().
 *
 * Callers MUST use the return value — normalization of non-standard file:// forms
 * only takes effect at the navigation site, not at the original URL.
 *
 * Callers (keep this list current, grep before removing):
 *   - write-commands.ts:goto
 *   - meta-commands.ts:diff (both URL args)

View on GitHub (pinned to 94993f7401)

Solutions

1. Use the three-slash local form: `file:///C:/Users/x.html` on Windows, `file:///tmp/x.html` on Unix.
2. For network/UNC shares, copy the file locally first — network file URLs are not supported.
3. If the segment was meant as a relative path that happens to contain a dot, use the explicit `file://./` prefix: `file://./docs.v1/page.html` is still rejected; rename or use `file:///cwd/docs.v1/page.html` via pathToFileURL.

Example fix

// before
await goto('file://C:/Users/me/index.html'); // 'C:' looks like host
// after
await goto('file:///C:/Users/me/index.html'); // three slashes = local absolute

const path = require('path');
const { pathToFileURL } = require('url');
function localFileUrl(p: string): string {
  // Always three-slash form for local absolute paths; rejects UNC/network.
  const abs = path.resolve(p);
  return pathToFileURL(abs).href;
}

const isLocalFileUrl = (u: string): boolean =>
  /^file:\/\/\/(?!\/)/.test(u) && // three slashes, not four
  !/[.:\\%]/.test(u.split('/')[3] ?? ''); // first path segment doesn't look like a host

try {
  await goto(url);
} catch (e: any) {
  if (/Unsupported file URL host/.test(e.message)) {
    // user passed a Windows drive letter or UNC — coerce to local three-slash form
    const local = url.replace(/^file:\/\//i, 'file:///');
    await goto(local);
  } else throw e;
}

When it happens

Trigger: Calling goto with `file://docs.v1/page.html` (dotted host), `file://127.0.0.1/x`, `file://[::1]/x` (IPv6), `file://C:/x` (Windows drive letter with colon), `file://host%20name/x` (percent-encoded host), or `file://share\dir/x` (backslash).

Common situations: Windows users pasting `file://C:/Users/x` (should be `file:///C:/Users/x` or `file:///C:\Users\x`); SMB/UNC paths `file://server/share`; copy-pasting a URL with a hostname where the local-path form was expected.

Related errors

• Invalid file URL: file:/// has no path. Use file:///<absolut
• Invalid file URL: ${url}. Use file:///<absolute-path> or fil
• Invalid file URL: file:// is empty. Use file:///<absolute-pa
• Invalid file URL: file://./ would list the current directory
• Invalid file URL: file://~/ would list the home directory. U

AI-assisted analysis of garrytan/gstack@94993f7401 (2026-08-12). Data as JSON: /api/errors/124674e96619483e. Report an issue: GitHub.