valyala/fasthttp · error

fasthttp: no free connections available to host

Error message

fasthttp: no free connections available to host

What it means

ErrNoFreeConns is returned when the per-host connection pool has no idle connections available and the configured maximum number of connections per host is already open. fasthttp refuses to create more connections to protect the host.

Source

Thrown at client.go:1787

	}

	return c.transport().RoundTrip(c, req, resp)
}

func (c *HostClient) transport() RoundTripper {
	if c.Transport == nil {
		return DefaultTransport
	}
	return c.Transport
}

var (
	// ErrNoFreeConns is returned when no free connections available
	// to the given host.
	//
	// Increase the allowed number of connections per host if you
	// see this error.
	ErrNoFreeConns = errors.New("fasthttp: no free connections available to host")

	// ErrConnectionClosed may be returned from client methods if the server
	// closes connection before returning the first response byte.
	//
	// If you see this error, then either fix the server by returning
	// 'Connection: close' response header before closing the connection
	// or add 'Connection: close' request header before sending requests
	// to broken server.
	ErrConnectionClosed = errors.New("fasthttp: the server closed connection before returning the first response byte. " +
		"make sure the server returns 'connection: close' response header before closing the connection")

	// ErrConnPoolStrategyNotImpl is returned when HostClient.ConnPoolStrategy is not implement yet.
	// If you see this error, then you need to check your HostClient configuration.
	ErrConnPoolStrategyNotImpl = errors.New("fasthttp: connection pool strategy is not implement")
)

type timeoutError struct{}

View on GitHub (pinned to c96f600972)

Solutions

1. Increase Client.MaxConnsPerHost to accommodate your concurrency
2. Fix why connections are busy: slow endpoints, long timeouts, or leaked response bodies
3. Add client-side throttling/queueing instead of overwhelming the pool
4. Retry with backoff on this error (e.g. via Client.RetryIf)

Example fix

// before
c := &fasthttp.Client{} // default per-host conns
// after
c := &fasthttp.Client{
    MaxConnsPerHost: 1024,
    MaxIdleConnDuration: 30 * time.Second,
    RetryIf: func(req *fasthttp.Request, resp *fasthttp.Response, err error) bool {
        return errors.Is(err, fasthttp.ErrNoFreeConns)
    },
}

if concurrencyLimit > client.MaxConnsPerHost {
    client.MaxConnsPerHost = concurrencyLimit
}

if errors.Is(err, fasthttp.ErrNoFreeConns) {
    time.Sleep(backoff)
    return do(req, resp) // bounded retry with jitter
}

When it happens

Trigger: High-concurrency Client/HostClient.Do calls to the same host when MaxConnsPerHost is saturated and all connections are busy; slow server responses keeping connections checked out.

Common situations: Load tests or burst traffic where MaxConnsPerHost is too low; slow downstream API causing connection pile-up; leaked long-lived responses pinning pooled connections.

Related errors

• fasthttp: the server closed connection before returning the
• fasthttp: connection pool strategy is not implement
• fasthttp: tls handshake timed out
• fasthttp: missing location header for http redirect
• fasthttp: too many redirects detected when doing the request

AI-assisted analysis of valyala/fasthttp@c96f600972 (2026-08-31). Data as JSON: /api/errors/b837958e2455de00. Report an issue: GitHub.