{"record":{"id":"b0aee3579d52d271","repo":"gofiber/fiber","slug":"failed-to-listen-w","errorCode":null,"errorMessage":"failed to listen: %w","messagePattern":"failed to listen: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"listen.go","lineNumber":283,"sourceCode":"\t}\n\n\t// Graceful shutdown\n\tif cfg.GracefulContext != nil {\n\t\tctx, cancel := context.WithCancel(cfg.GracefulContext)\n\t\tdefer cancel()\n\n\t\tgo app.gracefulShutdown(ctx, &cfg)\n\t}\n\n\t// Start prefork\n\tif cfg.EnablePrefork {\n\t\treturn app.prefork(addr, tlsConfig, &cfg)\n\t}\n\n\t// Configure Listener\n\tln, err := app.createListener(addr, tlsConfig, &cfg)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to listen: %w\", err)\n\t}\n\n\t// Close the listener on any path that doesn't reach Serve (which otherwise\n\t// takes ownership of it) — an early error return or a panicking hook — so\n\t// the bound socket isn't leaked.\n\tserved := false\n\tdefer func() {\n\t\tif !served {\n\t\t\t_ = ln.Close() //nolint:errcheck // best-effort cleanup on the error path\n\t\t}\n\t}()\n\n\t// prepare the server for the start\n\tapp.startupProcess()\n\n\tlistenData := app.prepareListenData(ln.Addr().String(), getTLSConfig(ln) != nil, &cfg, nil)\n\n\t// run hooks","sourceCodeStart":265,"sourceCodeEnd":301,"githubUrl":"https://github.com/gofiber/fiber/blob/a105acad6c1e4576a77f01e02973f67e962bb58d/listen.go#L265-L301","documentation":"Returned by App.Listen when app.createListener fails to bind the configured address. createListener wraps the underlying net.Listen / tls.Listen error as 'failed to listen', and Listen re-wraps it identically (listen.go:281/481), so the surfaced message is 'failed to listen: <net error>'. This is a socket-bind failure at server startup, before Serve runs.","triggerScenarios":"Calling app.Listen(\":3000\") when the port is already taken; binding to a privileged port (<1024) as a non-root user; an invalid/malformed address; a unix socket path whose directory is not writable; or TLS Listen with a bad tls.Config.","commonSituations":"Another process (or a previous instance that did not release the port) holds the address; Docker host-network or port-publishing conflicts; binding to 0.0.0.0 when only loopback is permitted; unix-socket mode where /run/app dir is missing or has wrong perms; systemd unit restarting before the old socket closes.","solutions":["Free the port: find and stop the holder (ss -ltnp / lsof -i :PORT) or pick a different port.","For privileged ports, grant CAP_NET_BIND_SERVICE or run on :8080 behind a reverse proxy.","For unix sockets, ensure the parent directory exists and is writable and set UnixSocketFileMode appropriately.","Add SO_REUSEADDR via a custom listener / startup retry-with-backoff for the restart race, and fail fast with a clear log."],"exampleFix":"// before\napp.Listen(\":80\") // permission denied for non-root\n\n// after\napp.Listen(\":8080\") // or grant CAP_NET_BIND_SERVICE to the binary","handlingStrategy":"retry","validationCode":"// preflight: is the address free before Listen?\nln, err := net.Listen(\"tcp\", addr)\nif err != nil {\n    log.Fatalf(\"address %s unavailable: %v\", addr, err)\n}\n_ = ln.Close()","typeGuard":"null","tryCatchPattern":"err := app.Listen(addr)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to listen\") {\n        // bind failure: port taken, permission denied, bad addr\n        log.Fatalf(\"cannot bind %s: %v\", addr, err)\n    }\n    log.Fatal(err)\n}","preventionTips":["Check the port is free (ss -ltnp / lsof) before starting, especially after a crash.","Avoid privileged ports (<1024) for non-root processes; use CAP_NET_BIND_SERVICE or :8080.","For unix sockets, ensure the parent dir exists and is writable; set UnixSocketFileMode.","Add bounded startup retry-with-backoff to survive the restart race for the same port."],"tags":["network","startup","configuration","socket","gofiber"],"backgroundTag":null,"analyzedSha":"a105acad6c1e4576a77f01e02973f67e962bb58d","analyzedAt":"2026-08-11T17:33:26.942Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}