{"record":{"id":"942dafc69a451402","repo":"valyala/fasthttp","slug":"fasthttp-the-server-closed-connection-before-retu","errorCode":null,"errorMessage":"fasthttp: the server closed connection before returning the first response byte. make sure the server returns 'connection: close' response header before closing the connection","messagePattern":"fasthttp: the server closed connection before returning the first response byte\\. make sure the server returns 'connection: close' response header before closing the connection","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client.go","lineNumber":1796,"sourceCode":"\treturn c.Transport\n}\n\nvar (\n\t// ErrNoFreeConns is returned when no free connections available\n\t// to the given host.\n\t//\n\t// Increase the allowed number of connections per host if you\n\t// see this error.\n\tErrNoFreeConns = errors.New(\"fasthttp: no free connections available to host\")\n\n\t// ErrConnectionClosed may be returned from client methods if the server\n\t// closes connection before returning the first response byte.\n\t//\n\t// If you see this error, then either fix the server by returning\n\t// 'Connection: close' response header before closing the connection\n\t// or add 'Connection: close' request header before sending requests\n\t// to broken server.\n\tErrConnectionClosed = errors.New(\"fasthttp: the server closed connection before returning the first response byte. \" +\n\t\t\"make sure the server returns 'connection: close' response header before closing the connection\")\n\n\t// ErrConnPoolStrategyNotImpl is returned when HostClient.ConnPoolStrategy is not implement yet.\n\t// If you see this error, then you need to check your HostClient configuration.\n\tErrConnPoolStrategyNotImpl = errors.New(\"fasthttp: connection pool strategy is not implement\")\n)\n\ntype timeoutError struct{}\n\nfunc (e *timeoutError) Error() string {\n\treturn \"fasthttp: timeout\"\n}\n\n// Timeout implements the Timeout behavior of the net.Error interface.\n// This allows for checks like:\n//\n//\tif x, ok := err.(interface{ Timeout() bool }); ok && x.Timeout() {\nfunc (e *timeoutError) Timeout() bool {","sourceCodeStart":1778,"sourceCodeEnd":1814,"githubUrl":"https://github.com/valyala/fasthttp/blob/c96f600972c6f4a7a30d664257b340ebe9d60124/client.go#L1778-L1814","documentation":"ErrConnectionClosed is returned when the server closes the connection before returning the first response byte. fasthttp retries idempotent requests automatically; for non-idempotent ones it surfaces this error and advises fixing keep-alive semantics on either side.","triggerScenarios":"Server keep-alive idle timeout elapses and the connection is closed just as the client sends a new request; non-idempotent (POST) requests are not retried so the error escapes; server restart/crash mid-request.","commonSituations":"Behind load balancers with short idle timeouts; servers closing idle conns; POST requests hitting a pooled connection that was reaped; frequent deploy restarts.","solutions":["Make the server send 'Connection: close' before closing, or align its idle timeout above the client's MaxIdleConnDuration","Set the request header 'Connection: close' when talking to a known-broken server","Configure Client.RetryIf to also retry ErrConnectionClosed for safe operations","Shorten Client.MaxIdleConnDuration so the client discards idle conns before the server does"],"exampleFix":"// before\nreq.Header.SetMethod(fasthttp.MethodPost) // non-idempotent, no retry on closed conn\n// after\nreq.Header.Set(\"Connection\", \"close\") // or:\nclient.RetryIf = func(_ *fasthttp.Request, _ *fasthttp.Response, err error) bool {\n    return errors.Is(err, fasthttp.ErrConnectionClosed)\n}","handlingStrategy":"retry","validationCode":"// keep client idle conns shorter-lived than the server's keep-alive timeout\nclient.MaxIdleConnDuration = serverKeepAliveTimeout - 5*time.Second","typeGuard":null,"tryCatchPattern":"if errors.Is(err, fasthttp.ErrConnectionClosed) {\n    return do(req, resp) // safe only if the operation is idempotent\n}","preventionTips":["Set 'Connection: close' when the server mishandles keep-alive","Align server idle timeout above client MaxIdleConnDuration","Only auto-retry idempotent requests or add idempotency keys","Retry transparently via Client.RetryIf"],"tags":["network","keep-alive","connection-closed","client"],"backgroundTag":"connection-closed-by-server","analyzedSha":"c96f600972c6f4a7a30d664257b340ebe9d60124","analyzedAt":"2026-08-31T22:48:28.265Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}