{"record":{"id":"657be6b8b018e674","repo":"kataras/iris","slug":"port-already-in-use-w","errorCode":null,"errorMessage":"port already in use: %w","messagePattern":"port already in use: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/netutil/tcp.go","lineNumber":76,"sourceCode":"\t// \tln, err = TCP(addr)\n\t// }\n\n\tln, err = TCP(addr, reuse)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treturn tcpKeepAliveListener{ln.(*net.TCPListener), keepAliveDur}, nil\n}\n\n// UNIX returns a new unix(file) Listener.\nfunc UNIX(socketFile string, mode os.FileMode) (net.Listener, error) {\n\tif errOs := os.Remove(socketFile); errOs != nil && !os.IsNotExist(errOs) {\n\t\treturn nil, fmt.Errorf(\"%s: %w\", socketFile, errOs)\n\t}\n\n\tl, err := net.Listen(\"unix\", socketFile)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"port already in use: %w\", err)\n\t}\n\n\tif err = os.Chmod(socketFile, mode); err != nil {\n\t\treturn nil, fmt.Errorf(\"cannot chmod %#o for %q: %w\", mode, socketFile, err)\n\t}\n\n\treturn l, nil\n}\n\n// TLS returns a new TLS Listener and an error on failure.\nfunc TLS(addr, certFile, keyFile string) (net.Listener, error) {\n\tif certFile == \"\" || keyFile == \"\" {\n\t\treturn nil, errors.New(\"empty certFile or KeyFile\")\n\t}\n\n\tcert, err := tls.LoadX509KeyPair(certFile, keyFile)\n\tif err != nil {\n\t\treturn nil, err","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/kataras/iris/blob/7bedaf55a0b64bbb2248a5845a2c60d81a30996a/core/netutil/tcp.go#L58-L94","documentation":"netutil.UNIX calls net.Listen(\"unix\", socketFile); if binding fails — most commonly because another process is already listening on that socket — it returns this wrapped \"port already in use\" error.","triggerScenarios":"Starting a second instance of the app while the first still holds the unix socket; the socket file exists and is live (removal succeeded but bind refused); socket path conflicts with another service.","commonSituations":"Duplicate deployment; supervisor restarting without killing the old process; systemd socket activation conflict; leftover socket whose owner process still runs.","solutions":["Stop the other process listening on the socket (lsof/fuser the socket path) or kill the duplicate instance.","Use a unique socket path per instance (include PID or instance name).","Ensure the previous instance cleanly removes its socket on shutdown (defer os.Remove).","After binding fails, also handle the chmod step failing — verify mode ownership afterwards."],"exampleFix":"// before\nln, _ := netutil.UNIX(\"/run/app.sock\", 0666) // in use\n// after\nif _, err := os.Stat(\"/run/app.sock\"); err == nil {\n    os.Remove(\"/run/app.sock\") // only if no live listener\n}\nln, _ := netutil.UNIX(\"/run/app.sock\", 0666)","handlingStrategy":"retry","validationCode":"if fi, err := os.Stat(socketFile); err == nil {\n    // check if a live process still listens before removing\n    conn, err := net.Dial(\"unix\", socketFile)\n    if err == nil { conn.Close(); return errors.New(\"socket in use\") }\n    os.Remove(socketFile)\n}","typeGuard":null,"tryCatchPattern":"ln, err := netutil.UNIX(socketFile, mode)\nif err != nil && strings.Contains(err.Error(), \"port already in use\") {\n    // stop the duplicate instance or pick a new path, then retry once\n    ln, err = netutil.UNIX(socketFile+\".2\", mode)\n}","preventionTips":["Ensure only one instance runs per socket path (pidfile/lockfile)","Remove the socket on clean shutdown (defer os.Remove)","Use per-instance socket names in multi-instance deployments"],"tags":["unix-socket","port-in-use","network"],"backgroundTag":"address-already-in-use","analyzedSha":"7bedaf55a0b64bbb2248a5845a2c60d81a30996a","analyzedAt":"2026-08-30T20:38:16.250Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}