networkAllowlist[${index}] must be a hostname, hostname:port

Error message

networkAllowlist[${index}] must be a hostname, hostname:port, or origin URL.

What it means

Thrown by parseNetworkAllowlistEntry when an entry cannot be parsed as a hostname, hostname:port, or origin URL. The function prepends 'https://' if no scheme is present, then constructs a URL; if URL parsing throws, or if the entry contains a path, username/password, query string, or fragment, this error fires.

Source

Thrown at packages/adapter-utils/src/local-process-sandbox.ts:134

  const realCommand = await fs.realpath(command).catch(() => command);
  paths.add(await nearestPackageRoot(realCommand));
  return Array.from(paths);
}

function parseNetworkAllowlistEntry(entry: string, index: number): NetworkAllowlistRule {
  const trimmed = entry.trim();
  if (!trimmed) throw new Error(`networkAllowlist[${index}] must not be empty.`);
  let hostname: string;
  let port: string | null;
  try {
    const parsed = new URL(trimmed.includes("://") ? trimmed : `https://${trimmed}`);
    if (parsed.username || parsed.password || parsed.pathname !== "/" || parsed.search || parsed.hash) {
      throw new Error("path");
    }
    hostname = parsed.hostname.toLowerCase();
    port = parsed.port || null;
  } catch {
    throw new Error(`networkAllowlist[${index}] must be a hostname, hostname:port, or origin URL.`);
  }
  if (!hostname || hostname === "*" || hostname.startsWith("*.")) {
    throw new Error(`networkAllowlist[${index}] must use an exact hostname; wildcards are not supported.`);
  }
  return { hostname, port };
}

export function parseLocalProcessNetworkAllowlist(value: unknown): string[] {
  if (!Array.isArray(value)) return [];
  return value.map((entry, index) => {
    if (typeof entry !== "string") throw new Error(`networkAllowlist[${index}] must be a string.`);
    const rule = parseNetworkAllowlistEntry(entry, index);
    return rule.port ? `${rule.hostname}:${rule.port}` : rule.hostname;
  });
}

export function parseLocalProcessNetworkScope(value: unknown): LocalProcessNetworkScope | null {
  if (value == null || value === "") return null;

View on GitHub (pinned to 67001ec6eb)

Solutions

Use only bare hostnames ('example.com'), hostname:port ('example.com:443'), or origin URLs ('https://example.com') in the allowlist.
Strip paths, query strings, fragments, and credentials from entries before adding them to the allowlist.
Validate entries with parseLocalProcessNetworkAllowlist during configuration loading.

Example fix

// before
const allowlist = ["https://api.example.com/v1/chat"];
// after
const allowlist = ["api.example.com"];

Defensive patterns

Strategy: validation

Validate before calling

function validateAllowlistEntry(entry: string): boolean {
  const trimmed = entry.trim();
  if (!trimmed) return false;
  try {
    const parsed = new URL(trimmed.includes("://") ? trimmed : `https://${trimmed}`);
    return !parsed.username && !parsed.password && parsed.pathname === "/" && !parsed.search && !parsed.hash;
  } catch {
    return false;
  }
}
const allValid = allowlist.every(validateAllowlistEntry);

Prevention

Use only bare hostnames or hostname:port pairs in the allowlist.
Strip paths, query strings, and credentials from entries before adding them.
Validate allowlist entries during configuration loading with parseLocalProcessNetworkAllowlist.

When it happens

Trigger: Calling parseLocalProcessNetworkAllowlist with an entry like 'example.com/api' (has a path), 'user:pass@example.com' (has credentials), 'example.com?q=1' (has query), or a completely malformed string like 'not a url'. The URL constructor or the path/credential checks reject it.

Common situations: An entry includes a full API path instead of just the origin ('https://api.example.com/v1/endpoint' instead of 'api.example.com'); credentials embedded in the URL; query parameters in the allowlist entry; a typo or non-URL string in the config.

Related errors

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/86d3631dc99cd9f4. Report an issue: GitHub.