{"record":{"id":"b42241f50c94d533","repo":"kataras/iris","slug":"failed-to-connect-to-the-server-after-d-retries","errorCode":null,"errorMessage":"failed to connect to the server after %d retries","messagePattern":"failed to connect to the server after (.+?) retries","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/host/waiter.go","lineNumber":119,"sourceCode":"\n\t\t\t// Increase the retry interval by the base raised to the power of the number of attempts.\n\t\t\t/*\n\t\t\t\t0\t2 seconds\n\t\t\t\t1\t4 seconds\n\t\t\t\t2\t8 seconds\n\t\t\t\t3\t~16 seconds\n\t\t\t\t4\t~32 seconds\n\t\t\t\t5\t~64 seconds\n\t\t\t\t6\t~128 seconds\n\t\t\t\t7\t~256 seconds\n\t\t\t\t8\t~512 seconds\n\t\t\t\t...\n\t\t\t*/\n\t\t\tretryInterval = time.Duration(math.Pow(base, float64(i+1))) * time.Second\n\t\t}\n\t}\n\t// All attempts failed, return an error.\n\treturn fmt.Errorf(\"failed to connect to the server after %d retries\", maxRetries)\n}\n\n// Fail is called by the server's Run method when the server failed to start.\nfunc (w *Waiter) Fail(err error) {\n\tw.mu.Lock()\n\tw.failure = err\n\tw.mu.Unlock()\n}\n\nfunc (w *Waiter) getFailure() error {\n\tw.mu.RLock()\n\terr := w.failure\n\tw.mu.RUnlock()\n\treturn err\n}\n","sourceCodeStart":101,"sourceCodeEnd":135,"githubUrl":"https://github.com/kataras/iris/blob/7bedaf55a0b64bbb2248a5845a2c60d81a30996a/core/host/waiter.go#L101-L135","documentation":"The Waiter polls the server address with exponential backoff after startup; if none of the retries can establish a connection it returns this error, meaning the server did not become reachable in time.","triggerScenarios":"Calling host Wait / supervisor Wait when the HTTP server failed to bind (port in use, permission denied) or crashed before accepting connections; firewall blocking localhost connect.","commonSituations":"Port already occupied; trying to bind a privileged port (<1024) without permissions; server panicked at startup; running in a container where the address resolves differently.","solutions":["Inspect the server's failure via Waiter.Fail logs / Run error to find the root cause (e.g. \"port already in use\").","Free the port or choose another one; ensure the process can bind the address.","Increase maxRetries/startup timeout in slow environments, or check that the app actually called ListenAndServe.","Verify networking (firewall, docker port mapping, IPv4/IPv6 mismatch) allows connecting to the address."],"exampleFix":"// before\nw.Wait(addr) // fails after N retries\n// after\nif err := w.Wait(addr); err != nil {\n    log.Fatalf(\"server not reachable: %v; root cause: %v\", err, w.(*host.Waiter).GetFailure())\n}\n","handlingStrategy":"retry","validationCode":"// pre-check port availability before starting the server\nconn, err := net.DialTimeout(\"tcp\", addr, time.Second)\nif err == nil { conn.Close(); return errors.New(\"port already in use\") }","typeGuard":null,"tryCatchPattern":"if err := w.Wait(addr); err != nil {\n    if failure := waiter.GetFailure(); failure != nil {\n        log.Fatalf(\"server start failed: %v (root cause: %v)\", err, failure)\n    }\n    // optionally retry startup with backoff\n}","preventionTips":["Check that the bind address/port is free before starting","Inspect Waiter.Fail / GetFailure for the root cause","Allow adequate retries in slow containerized environments"],"tags":["network","startup","connection"],"backgroundTag":"connection-refused","analyzedSha":"7bedaf55a0b64bbb2248a5845a2c60d81a30996a","analyzedAt":"2026-08-30T20:38:16.250Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}