usebruno/bruno · error · Error

Proxy protocol and hostname are required when proxy is enabl

Error message

Proxy protocol and hostname are required when proxy is enabled

What it means

When proxyMode is 'on' and the URL is not bypassed, the loader requires both protocol and hostname in the proxy config; a falsy value for either throws before constructing the proxy URI. Prevents producing a malformed proxy URL like '://:0'.

Source

Thrown at packages/bruno-requests/src/utils/http-https-agents.ts:503

  let httpsAgent: HttpsAgent | HttpsProxyAgent<any> | SocksProxyAgent | undefined;

  // Determine if this is an HTTPS request
  const isHttpsRequest = requestUrl ? requestUrl.startsWith('https:') : true;

  // Extract hostname for per-host agent caching (enables TLS session reuse per host)
  const hostname = extractHostname(requestUrl);

  if (proxyMode === 'on') {
    const shouldProxy = shouldUseProxy(requestUrl, get(proxyConfig, 'bypassProxy', ''));
    if (shouldProxy) {
      const proxyProtocol = get(proxyConfig, 'protocol');
      const proxyHostname = get(proxyConfig, 'hostname');
      const proxyPort = get(proxyConfig, 'port');
      const proxyAuthEnabled = !get(proxyConfig, 'auth.disabled', false);
      const socksEnabled = proxyProtocol && proxyProtocol.includes('socks');

      if (!proxyProtocol || !proxyHostname) {
        throw new Error('Proxy protocol and hostname are required when proxy is enabled');
      }

      const uriPort = isUndefined(proxyPort) || isNull(proxyPort) ? '' : `:${proxyPort}`;
      let proxyUri: string;
      if (proxyAuthEnabled) {
        const proxyAuthUsername = encodeURIComponent(get(proxyConfig, 'auth.username', ''));
        const proxyAuthPassword = encodeURIComponent(get(proxyConfig, 'auth.password', ''));
        proxyUri = `${proxyProtocol}://${proxyAuthUsername}:${proxyAuthPassword}@${proxyHostname}${uriPort}`;
      } else {
        proxyUri = `${proxyProtocol}://${proxyHostname}${uriPort}`;
      }

      // When the proxy itself uses HTTPS, the agent connecting to it needs TLS options
      // (e.g., ca certs) even for plain HTTP requests
      const isHttpsProxy = proxyProtocol === 'https';
      const httpProxyAgentOptions = isHttpsProxy ? { keepAlive: true, ...tlsOptions } : { keepAlive: true };

      // Only set the agent needed for the request protocol

View on GitHub (pinned to 9bdd81c7bd)

Solutions

1. In Preferences/Collection proxy settings, set both protocol (http/https/socks4/socks5) and hostname.
2. If you do not actually need a proxy, switch proxyMode to 'off' or 'system'.
3. Add the URL to bypassProxy if this host should skip the proxy.

Example fix

// before
{ proxyMode:'on', proxyConfig:{ protocol:'', hostname:'', port:8080 } }

// after
{ proxyMode:'on', proxyConfig:{ protocol:'http', hostname:'proxy.corp', port:8080 } }

if (proxyMode === 'on') {
  const protocol = get(proxyConfig,'protocol'), hostname = get(proxyConfig,'hostname');
  if (!protocol || !hostname) throw new Error('Proxy protocol and hostname are required when proxy is enabled');
}

function isValidManualProxy(c): boolean { return !!c && typeof c.protocol==='string' && !!c.protocol && typeof c.hostname==='string' && !!c.hostname; }

When it happens

Trigger: Proxy enabled (proxyMode='on'), shouldUseProxy returned true for the URL, but proxyConfig.protocol and/or proxyConfig.hostname are empty/undefined.

Common situations: User toggled proxy on but left host/protocol blank; partial proxy config saved; collection-level proxy overrode app-level with an empty object; protocol field renamed in a settings migration.

Related errors

• Invalid system http_proxy "${http_proxy}": ${error.message}
• Invalid system https_proxy "${https_proxy}": ${error.message
• Workspace path is required
• Workspace configuration must be an object
• Invalid workspace: not a bruno workspace

AI-assisted analysis of usebruno/bruno@9bdd81c7bd (2026-08-13). Data as JSON: /api/errors/8d7eb06e0417e450. Report an issue: GitHub.