garrytan/gstack · error · ProxyConfigError

invalid proxy URL — could not parse

Error message

invalid proxy URL — could not parse

What it means

Thrown by parseProxyConfig when `new URL(opts.proxyUrl)` throws — the supplied proxy URL string is not parseable as a URL at all. The hint directs the user to the expected scheme://[user:pass@]host:port shape.

Source

Thrown at browse/src/proxy-config.ts:49

  }
}

/**
 * Parse the BROWSE_PROXY_URL string and merge env-supplied creds.
 *
 * @throws ProxyConfigError on malformed URL, unsupported scheme, or
 *   ambiguous credentials (set in both URL and env).
 */
export function parseProxyConfig(opts: {
  proxyUrl: string;
  envUser?: string;
  envPass?: string;
}): ParsedProxyConfig {
  let url: URL;
  try {
    url = new URL(opts.proxyUrl);
  } catch {
    throw new ProxyConfigError(
      'expected scheme://[user:pass@]host:port',
      `invalid proxy URL — could not parse`,
    );
  }

  const scheme = url.protocol.replace(':', '');
  if (scheme !== 'socks5' && scheme !== 'http' && scheme !== 'https') {
    throw new ProxyConfigError(
      'use socks5://, http://, or https://',
      `unsupported proxy scheme '${scheme}'`,
    );
  }

  if (!url.hostname) {
    throw new ProxyConfigError(
      'expected scheme://[user:pass@]host:port',
      `invalid proxy URL — missing host`,
    );

View on GitHub (pinned to 94993f7401)

Solutions

1. Add the scheme: prefix with socks5://, http://, or https://
2. Strip stray whitespace and surrounding quotes from the value
3. Validate before use: `node -e "new URL(process.argv[1])" <url>`
4. If using a shell variable, guard it: `${BROWSE_PROXY_URL:?missing}`

Example fix

# before
BROWSE_PROXY_URL=localhost:1080  # throws — no scheme

# after
BROWSE_PROXY_URL=socks5://localhost:1080

function isValidProxyUrl(s: string): boolean {
  try {
    const u = new URL(s);
    return ['socks5:', 'http:', 'https:'].includes(u.protocol) && !!u.hostname;
  } catch { return false; }
}

if (!isValidProxyUrl(proxyUrl)) {
  throw new Error('proxy URL must be scheme://[user:pass@]host:port with scheme socks5|http|https');
}

function isParsableUrl(s: string): boolean {
  try { new URL(s); return true; } catch { return false; }
}

try {
  const cfg = parseProxyConfig({ proxyUrl, envUser, envPass });
} catch (e) {
  if (e instanceof ProxyConfigError && /could not parse/.test(e.message)) {
    console.error(`${e.message}. Hint: ${e.hint}`);
  }
  throw e;
}

When it happens

Trigger: Setting BROWSE_PROXY_URL or --proxy to a malformed string: missing scheme ('localhost:1080'), stray characters, unencoded spaces, or a value that is not a URL.

Common situations: Forgetting the scheme prefix (the most common cause — '127.0.0.1:1080' is not a valid URL without a scheme); copy-paste with trailing whitespace, quotes, or newlines; shell variable that expanded to empty or partial.

Related errors

• unsupported proxy scheme '${scheme}'
• invalid proxy URL — missing host
• invalid proxy URL — bad port
• proxy creds set in both env (BROWSE_PROXY_USER) and URL — pi
• API error (${response.status}): ${error.slice(0, 300)}

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