gofiber/fiber · error

fasthttp.HostClient must not be nil

Error message

fasthttp.HostClient must not be nil

What it means

Panics from client/client.go:944 inside the fiber client constructor NewWithHostClient when the supplied *fasthttp.HostClient is nil. The fiber HTTP client wraps a fasthttp transport; a nil transport has no connection pool, dialer, or timeout state, so every subsequent request would nil-deref. The library treats this as a programmer error and fails fast at construction rather than corrupting state later.

Source

Thrown at client/client.go:944

func New() *Client {
	// Follow-up performance optimizations:
	// Try to use a pool to reduce the memory allocation cost for the Fiber client and the fasthttp client.
	// If possible, also consider pooling other structs (e.g., request headers, cookies, query parameters, path parameters).
	return NewWithClient(&fasthttp.Client{})
}

// NewWithClient creates and returns a new Client object from an existing fasthttp.Client.
func NewWithClient(c *fasthttp.Client) *Client {
	if c == nil {
		panic("fasthttp.Client must not be nil")
	}
	return newClient(newStandardClientTransport(c))
}

// NewWithHostClient creates and returns a new Client object from an existing fasthttp.HostClient.
func NewWithHostClient(c *fasthttp.HostClient) *Client {
	if c == nil {
		panic("fasthttp.HostClient must not be nil")
	}
	return newClient(newHostClientTransport(c))
}

// NewWithLBClient creates and returns a new Client object from an existing fasthttp.LBClient.
func NewWithLBClient(c *fasthttp.LBClient) *Client {
	if c == nil {
		panic("fasthttp.LBClient must not be nil")
	}
	return newClient(newLBClientTransport(c))
}

func newClient(transport httpClientTransport) *Client {
	return &Client{
		transport: transport,
		header: &Header{
			RequestHeader: &fasthttp.RequestHeader{},
		},

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Guarantee the *fasthttp.HostClient is allocated before calling NewWithHostClient; construct it inline: client.NewWithHostClient(&fasthttp.HostClient{Addr: "example.com:80"}).
2. If the HostClient comes from a factory that can fail, check for nil first and fall back to client.New() or return the error up the stack.
3. Add a nil check in the factory and log/return a configuration error instead of propagating a nil pointer.

Example fix

// before
var hc *fasthttp.HostClient
app := client.NewWithHostClient(hc)

// after
app := client.NewWithHostClient(&fasthttp.HostClient{
    Addr:                upstream,
    MaxConns:            100,
    ReadTimeout:         5 * time.Second,
})

func buildHostClient(addr string) (*fasthttp.HostClient, error) {
    if addr == "" {
        return nil, errors.New("upstream address required")
    }
    return &fasthttp.HostClient{Addr: addr, MaxConns: 100}, nil
}

hc, err := buildHostClient(upstream)
if err != nil || hc == nil {
    return fmt.Errorf("host client setup: %w", err)
}
app := client.NewWithHostClient(hc)

func isHostClientReady(c *fasthttp.HostClient) bool {
    return c != nil && c.Addr != ""
}

When it happens

Trigger: Calling client.NewWithHostClient(nil), or passing a pointer variable that was declared but never initialized (var hc *fasthttp.HostClient; client.NewWithHostClient(hc)). The panic fires immediately, before any request is sent.

Common situations: Conditionally building the HostClient (e.g. only when a feature flag is on) and passing the zero-value pointer when the flag is off; refactoring that moved HostClient creation into a helper that can return nil on a config parse error; tests that stub the transport with nil.

Related errors

• fasthttp.LBClient must not be nil
• fasthttp.Client must not be nil
• proxy: nil client override passed to Do/Forward
• client: invalid proxy URL: %w
• client panic: %v

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