garrytan/gstack · error · ProxyConfigError

unsupported proxy scheme '${scheme}'

Error message

unsupported proxy scheme '${scheme}'

What it means

Thrown by parseProxyConfig when the URL parses successfully but its protocol is not one of socks5, http, or https. Any other scheme (ftp, socks4, smtp, file) is refused because the downstream SOCKS bridge / Chromium launcher only supports those three.

Source

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

 */
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`,
    );
  }

  const port = url.port
    ? parseInt(url.port, 10)
    : (scheme === 'http' ? 80 : scheme === 'https' ? 443 : 1080);
  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
    throw new ProxyConfigError(
      'expected scheme://[user:pass@]host:port',

View on GitHub (pinned to 94993f7401)

Solutions

1. Switch socks4:// to socks5:// (and confirm the proxy actually speaks SOCKS5)
2. Use http:// or https:// for HTTP/HTTPS proxies
3. Correct typos: 'socks://' is not valid — pick socks5://, http://, or https://
4. Confirm the proxy server's actual protocol with its operator

Example fix

# before
BROWSE_PROXY_URL=socks4://proxy.local:1080  # throws

# after
BROWSE_PROXY_URL=socks5://proxy.local:1080

const ALLOWED = new Set(['socks5:', 'http:', 'https:']);

function hasSupportedScheme(s: string): boolean {
  try { return ALLOWED.has(new URL(s).protocol); }
  catch { return false; }
}

if (!hasSupportedScheme(proxyUrl)) {
  throw new Error('Proxy scheme must be socks5, http, or https');
}

function isSupportedProxyScheme(s: string): boolean {
  try { return ALLOWED.has(new URL(s).protocol); } catch { return false; }
}

try {
  parseProxyConfig(opts);
} catch (e) {
  if (e instanceof ProxyConfigError && /unsupported proxy scheme/.test(e.message)) {
    console.error(`Scheme not supported. ${e.hint}`);
  }
  throw e;
}

When it happens

Trigger: Passing a proxy URL whose scheme is unsupported: socks4://, ftp://, ssh://, or a typo like 'socks://'.

Common situations: SOCKS4 proxy mistakenly written as socks4:// when only socks5 is supported; legacy proxy URL with an old scheme; typo in the scheme string; copy-pasted a URL from a tool that uses a different protocol name.

Related errors

• invalid proxy URL — could not parse
• 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/1c4a9d049b0bc6da. Report an issue: GitHub.