gofiber/fiber · error

client: invalid proxy URL: %w

Error message

client: invalid proxy URL: %w

What it means

Returned by Client.SetProxyURL (client/client.go:369) when the fasthttpproxy dialer cannot build a dial function from the supplied proxy URL. The client builds a fasthttpproxy.Dialer with the URL as both HTTPProxy and HTTPSProxy and calls GetDialFunc; if that returns an error it is wrapped and returned to the caller instead of being silently swallowed later by the fasthttp dialer. Supported schemes are the ones fasthttpproxy understands (http, https, socks5, socks5h); anything else fails here.

Source

Thrown at client/client.go:369

		c.logger.Panicf("client: %v", ErrFailedToAppendCert)
	}

	return c
}

// SetProxyURL sets the proxy URL for the client. This affects all subsequent requests.
func (c *Client) SetProxyURL(proxyURL string) error {
	c.mu.Lock()
	defer c.mu.Unlock()

	// Build the fasthttp proxy dialer directly so invalid proxy URLs are returned
	// to callers instead of being swallowed by FasthttpHTTPDialer.
	dialer := fasthttpproxy.Dialer{
		Config: httpproxy.Config{HTTPProxy: proxyURL, HTTPSProxy: proxyURL},
	}
	dialFunc, err := dialer.GetDialFunc(false)
	if err != nil {
		return fmt.Errorf("client: invalid proxy URL: %w", err)
	}
	c.applyDial(dialFunc)
	return nil
}

// RetryConfig returns a copy of the current retry configuration.
func (c *Client) RetryConfig() *RetryConfig {
	c.mu.RLock()
	defer c.mu.RUnlock()

	if c.retryConfig == nil {
		return nil
	}

	cfg := *c.retryConfig
	return &cfg
}

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Check the error returned by SetProxyURL before issuing any requests and fail fast with the configured URL.
2. Use a supported scheme: http://, https://, socks5://, or socks5h:// — ftp:// and bare host:port are rejected.
3. Validate the proxy URL with net/url.Parse first and ensure Scheme and Host are non-empty before calling SetProxyURL.
4. Fall back to a direct connection (skip SetProxyURL) when the configured proxy is empty or known-invalid.

Example fix

// before
_ = client.SetProxyURL(proxyFromEnv) // error ignored

// after — validate scheme, surface the error
u, err := url.Parse(proxyFromEnv)
if err != nil || u.Host == "" {
    return fmt.Errorf("bad proxy URL %q: %w", proxyFromEnv, err)
}
if err := client.SetProxyURL(proxyFromEnv); err != nil {
    return fmt.Errorf("SetProxyURL: %w", err)
}

// Validate the proxy URL scheme/host before calling SetProxyURL.
func validProxyURL(s string) error {
    u, err := url.Parse(s)
    if err != nil {
        return err
    }
    switch u.Scheme {
    case "http", "https", "socks5", "socks5h":
    default:
        return fmt.Errorf("unsupported proxy scheme %q", u.Scheme)
    }
    if u.Host == "" {
        return errors.New("proxy URL missing host")
    }
    return nil
}

if err := client.SetProxyURL(proxy); err != nil {
    log.Printf("proxy unusable, continuing direct: %v", err)
    // proceed without a proxy
}

When it happens

Trigger: Calling client.SetProxyURL("ftp://127.0.0.1:8080") (the test-suite reproducer), passing a URL with an unsupported scheme, a malformed URL (missing host, unparseable), or SOCKS credentials that fasthttpproxy rejects. Also triggered by reading the proxy from an env var that is empty or corrupt.

Common situations: Reading HTTP_PROXY/HTTPS_PROXY from the environment and passing it unchecked; a typo in the scheme (fttp://, htt://); pasting a proxy address without a scheme; rotating to a SOCKS proxy whose auth string is malformed; CI environment where the proxy var points at an internal scheme the library does not support.

Related errors

• proxy: nil client override passed to Do/Forward
• proxy: upstream host resolves to a blocked address
• failed to resolve TCP address after adding port: %w
• Servers cannot be empty
• proxy: WithClient requires a non-nil *fasthttp.Client

AI-assisted analysis of gofiber/fiber@9a4c7e57fe (2026-08-04). Data as JSON: /data/errors/106fb3c8f02c32c2.json. Report an issue: GitHub.