{"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":267,"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":249,"sourceCodeEnd":285,"githubUrl":"https://github.com/gofiber/fiber/blob/9a4c7e57fe0b080a04235d28a4b0d2b4b353d58c/listen.go#L249-L285","documentation":"Returned by App.Listen when createListener fails to bind the configured address. This wraps any net.Listen / tls.Listen failure (port already in use, permission denied on privileged port, invalid address, unix socket error) at the top level of Listen(). The underlying cause is preserved via %w.","triggerScenarios":"Calling app.Listen(\":8080\") when port 8080 is already bound by another process; binding a privileged port (<1024) without root; an invalid address format; or a unix socket path whose parent directory doesn't exist. With TLS, tls.Listen can also fail if the TLS config is invalid.","commonSituations":"Another instance of the server already running on the same port, a leftover process, Docker port collision, binding :80/:443 as a non-root user, or a stale unix socket file.","solutions":["Find and stop the process holding the port: lsof -i :8080 or ss -lntp.","Use a different port or enable SO_REUSEADDR via a custom listener.","Run as root/cap-net-bind-service for privileged ports, or use a non-privileged port with port forwarding.","For unix sockets, remove the stale socket file before listening (Fiber does this automatically, but check the parent dir).","Validate the address format before calling Listen."],"exampleFix":"// before\napp.Listen(\":8080\") // EADDRINUSE\n\n// after\n// free the port, or bind a free one:\napp.Listen(\":8081\")","handlingStrategy":"try-catch","validationCode":"// Check the port is free before calling Listen\nl, err := net.Listen(\"tcp\", addr)\nif err != nil {\n    return fmt.Errorf(\"port check failed: %w\", err)\n}\nl.Close()","typeGuard":null,"tryCatchPattern":"if err := app.Listen(addr); err != nil {\n    log.Errorf(\"listen failed: %v\", err)\n    // optionally retry on a different port or exit\n}","preventionTips":["Ensure no other process holds the port (lsof/ss).","Use SO_REUSEADDR via a custom listener where appropriate.","Avoid privileged ports without root or CAP_NET_BIND_SERVICE.","Remove stale unix socket files before binding."],"tags":["network","listen","port","startup","go"],"analyzedSha":"9a4c7e57fe0b080a04235d28a4b0d2b4b353d58c","analyzedAt":"2026-08-04T21:44:03.395Z","schemaVersion":2}