networkAllowlist[${index}] must use an exact hostname; wildc

Error message

networkAllowlist[${index}] must use an exact hostname; wildcards are not supported.

What it means

Thrown by parseNetworkAllowlistEntry when the parsed hostname is empty, is exactly '*', or starts with '*.'. The sandbox network allowlist requires exact hostnames for security — wildcard matching would broaden network egress beyond what the operator intended, so it is explicitly rejected.

Source

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

}

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;
  if (value === "deny" || value === "allowlist") return value;
  throw new Error('networkScope must be "deny" or "allowlist".');
}

View on GitHub (pinned to 67001ec6eb)

Solutions

List each exact hostname individually instead of using wildcards.
If subdomain matching is needed, enumerate all subdomains or use a more specific pattern that resolves to exact hostnames.
Replace any '*' placeholder values in configuration templates with concrete hostnames before deployment.

Example fix

// before
const allowlist = ["*.example.com"];
// after
const allowlist = ["api.example.com", "www.example.com", "cdn.example.com"];

Defensive patterns

Strategy: validation

Validate before calling

function hasNoWildcards(hostname: string): boolean {
  const trimmed = hostname.trim().toLowerCase();
  return trimmed.length > 0 && trimmed !== "*" && !trimmed.startsWith("*.");
}
const allExact = allowlist.every(hasNoWildcards);

Prevention

Enumerate exact hostnames instead of using wildcards.
Replace placeholder '*' values in config templates with concrete hostnames before deployment.
Document the exact-hostname-only policy in the sandbox configuration guide.

When it happens

Trigger: Calling parseLocalProcessNetworkAllowlist with an entry like '*' (match all), '*.example.com' (wildcard subdomain), or an entry whose URL hostname resolves to empty after parsing.

Common situations: A developer tries to allow all subdomains with '*.example.com' expecting glob-style matching; a config template uses '*' as a placeholder that was never replaced; an entry like 'https://:443' produces an empty hostname.

Related errors

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