{"record":{"id":"0bc9cb20d45e1515","repo":"oven-sh/bun","slug":"unsupportedproxyprotocol","errorCode":"UnsupportedProxyProtocol","errorMessage":"UnsupportedProxyProtocol","messagePattern":"UnsupportedProxyProtocol","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/http/error.rs","lineNumber":98,"sourceCode":"    #[error(\"WantWrite\")]\n    WantWrite,\n    #[error(\"HTTP3HandshakeFailed\")]\n    HTTP3HandshakeFailed,\n    #[error(\"HTTP3ProtocolError\")]\n    HTTP3ProtocolError,\n    #[error(\"HTTP3HeaderEncodingError\")]\n    HTTP3HeaderEncodingError,\n    #[error(\"DNSResolutionFailed\")]\n    DNSResolutionFailed,\n    #[error(\"HTTP3StreamReset\")]\n    HTTP3StreamReset,\n    #[error(\"HTTP3ContentLengthMismatch\")]\n    HTTP3ContentLengthMismatch,\n    #[error(\"FailedToOpenSocket\")]\n    FailedToOpenSocket,\n    #[error(\"InvalidCRL\")]\n    InvalidCRL,\n    #[error(\"UnsupportedProxyProtocol\")]\n    UnsupportedProxyProtocol,\n    #[error(transparent)]\n    Cert(#[from] CertError),\n    #[error(transparent)]\n    Alloc(#[from] bun_alloc::AllocError),\n    #[error(transparent)]\n    Hpack(#[from] crate::lshpack::HpackError),\n    #[error(transparent)]\n    Core(#[from] bun_core::Error),\n    #[error(transparent)]\n    Sys(#[from] bun_errno::SystemErrno),\n    #[error(transparent)]\n    Zlib(bun_zlib::ZlibError),\n    #[error(transparent)]\n    Brotli(bun_brotli::Error),\n    #[error(transparent)]\n    Zstd(bun_zstd::ZstdError),\n    #[error(transparent)]","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/oven-sh/bun/blob/8c5296ac459e8252d3cd702f3fbcbb0c249d95d5/src/http/error.rs#L80-L116","documentation":"Thrown by Bun's HTTP client when a proxy URL is configured but its scheme is neither empty nor http/https. Bun only supports HTTP-style (forward and CONNECT) proxies: the check in src/http/HTTPThread.rs (`url.protocol.is_empty() || url.has_http_like_protocol()`) rejects anything else before any socket is opened. It surfaces as a rejected fetch promise (or Bun.connect error) with `code: \"UnsupportedProxyProtocol\"` (see test/js/bun/http/proxy.test.ts:378).","triggerScenarios":"Calling fetch(url, { proxy: \"socks5://...\" }) or any proxy string whose scheme is not http:// or https:// (ftp://, socks4://, socks5h://, etc.), or setting HTTP_PROXY / HTTPS_PROXY / BUN_CONFIG_PROXY to a non-HTTP scheme so every outbound fetch/Bun.connect inherits it. Also triggered via WebSocket through such a proxy (src/jsc/bindings/webcore/WebSocket.cpp mirrors the fetch behavior).","commonSituations":"Corporate SOCKS proxies (very common in enterprise/VPN setups), copy-pasting an scp/ssh-style proxy string, curl users assuming socks5h works like in curl, CI environments that export ALL_PROXY=socks5://... globally, or a proxy string missing the scheme where the URL parser assigned an unexpected protocol.","solutions":["Change the proxy URL to an http:// or https:// scheme (e.g. a local HTTP-to-SOCKS bridge such as privoxy/gost if only SOCKS exists)","If the string was scheme-less, keep it empty-protocol (Bun accepts an empty protocol) or explicitly write http://proxyhost:port","Unset or fix the offending env var (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, BUN_CONFIG_PROXY) if you did not pass `proxy` explicitly","For SOCKS-only environments, run a local HTTP proxy that forwards to SOCKS and point Bun at that","Catch the rejection and fail with a clear message if an unsupported proxy is a supported configuration in your app"],"exampleFix":"// before\nawait fetch(\"https://httpbin.org/get\", { proxy: \"socks5://asdf.com\" });\n// TypeError: UnsupportedProxyProtocol\n\n// after\nawait fetch(\"https://httpbin.org/get\", { proxy: \"http://127.0.0.1:8080\" }); // HTTP proxy that bridges to SOCKS upstream","handlingStrategy":"validation","validationCode":"function assertSupportedProxy(proxy: string | URL | undefined) {\n  if (proxy == null) return;\n  const proto = new URL(proxy).protocol.replace(\":\", \"\");\n  if (proto !== \"http\" && proto !== \"https\") {\n    throw new Error(\n      `Bun only supports http/https proxies, got '${proto}://' — use an HTTP-to-SOCKS bridge`\n    );\n  }\n}\nassertSupportedProxy(process.env.HTTP_PROXY);\nawait fetch(\"https://example.com\", { proxy: \"http://127.0.0.1:8080\" });","typeGuard":"function isUnsupportedProxyProtocolError(e: unknown): e is Error & { code: \"UnsupportedProxyProtocol\" } {\n  return e instanceof Error && (e as any).code === \"UnsupportedProxyProtocol\";\n}","tryCatchPattern":"try {\n  await fetch(url, { proxy });\n} catch (e) {\n  if (isUnsupportedProxyProtocolError(e)) {\n    // fall back to direct, or surface a config error — do not retry the same proxy\n    throw new Error(`Proxy '${proxy}' uses an unsupported scheme; use http:// or https://`);\n  }\n  throw e;\n}","preventionTips":["Validate the proxy scheme at config-load time, before the first fetch","Keep env-var-driven proxy config (HTTP_PROXY/HTTPS_PROXY/BUN_CONFIG_PROXY) out of CI secrets where socks5 schemes sneak in","Document that Bun supports HTTP CONNECT proxies only; add a lint/test asserting your proxy constant starts with http"],"tags":["network","proxy","fetch","configuration"],"backgroundTag":null,"analyzedSha":"8c5296ac459e8252d3cd702f3fbcbb0c249d95d5","analyzedAt":"2026-08-16T08:01:58.794Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}