gofiber/fiber · error

proxy: WithClient requires a non-nil *fasthttp.Client

Error message

proxy: WithClient requires a non-nil *fasthttp.Client

What it means

proxy.WithClient installs a global *fasthttp.Client used to dispatch proxied requests and installs an SSRF guard on its dial path. Passing nil leaves no client to dispatch through, so WithClient panics. The guard requires a concrete client to attach to.

Source

Thrown at middleware/proxy/proxy.go:230

		return // already guarded (directly or composed with a user hook)
	}
	cli.ConfigureClient = (&guardedConfigureClient{orig: existing}).run
}

func init() {
	ensureClientGuarded(defaultClient)
	client.Store(defaultClient)
}

// WithClient sets the global proxy client.
// This function should be called before Do and Forward — doing so installs
// the dial-time SSRF guard (via the client's ConfigureClient hook,
// composing with any hook it already carries) before the client dials any
// host, so requests dispatched through it re-validate the resolved IP at
// connect time, matching the default client's behavior.
func WithClient(cli *fasthttp.Client) {
	if cli == nil {
		panic("proxy: WithClient requires a non-nil *fasthttp.Client")
	}

	ensureClientGuarded(cli)
	client.Store(cli)
}

// Forward performs the given http request and fills the given http response.
// This method will return a fiber.Handler
//
// SSRF note: Forward validates the upstream host against the active
// SecurityPolicy up front and, when AllowPrivateIPs is false, re-validates
// the resolved IP at dial time via the guard installed on the dispatching
// client, so a rebinding-capable resolver cannot swap a public answer for
// a private one between validation and connection.
func Forward(addr string, clients ...*fasthttp.Client) fiber.Handler {
	return func(c fiber.Ctx) error {
		c.Request().Header.Set("X-Real-IP", c.IP())
		return Do(c, addr, clients...)

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Construct a *fasthttp.Client with fasthttp.New() or &fasthttp.Client{} and pass that instance.
2. Check the client for nil before calling WithClient.
3. Handle any error from the client factory before passing its result.

Example fix

// before
proxy.WithClient(nil)
// after
cli := &fasthttp.Client{}
proxy.WithClient(cli)

if cli == nil {
    log.Fatal("proxy: WithClient requires a non-nil *fasthttp.Client")
}
proxy.WithClient(cli)

func isValidProxyClient(cli *fasthttp.Client) bool {
    return cli != nil
}

When it happens

Trigger: Calling proxy.WithClient(nil), or passing a client variable that was never initialized (e.g. returned nil from a constructor that errored, with the error ignored).

Common situations: Initializing a client conditionally and passing the zero-value pointer. Refactoring and removing the client creation but keeping the WithClient call. A factory function returns (nil, err) and only the nil is passed.

Related errors

• route handler 'fn' cannot be nil
• fiber: Config.RegexHandler must not return nil
• Servers cannot be empty
• Servers cannot be empty
• proxy: nil client override passed to Do/Forward

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