{"record":{"id":"fa7afdee4407c565","repo":"valyala/fasthttp","slug":"unexpected-error-when-trying-to-remove-unix-socket","errorCode":null,"errorMessage":"unexpected error when trying to remove unix socket file %q: %w","messagePattern":"unexpected error when trying to remove unix socket file %q: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server.go","lineNumber":1786,"sourceCode":"// such as IPv6.\n//\n// Accepted connections are configured to enable TCP keep-alives.\nfunc (s *Server) ListenAndServe(addr string) error {\n\tln, err := net.Listen(\"tcp4\", addr)\n\tif err != nil {\n\t\treturn err\n\t}\n\treturn s.Serve(ln)\n}\n\n// ListenAndServeUNIX serves HTTP requests from the given UNIX addr.\n//\n// The function deletes existing file at addr before starting serving.\n//\n// The server sets the given file mode for the UNIX addr.\nfunc (s *Server) ListenAndServeUNIX(addr string, mode os.FileMode) error {\n\tif err := os.Remove(addr); err != nil && !os.IsNotExist(err) {\n\t\treturn fmt.Errorf(\"unexpected error when trying to remove unix socket file %q: %w\", addr, err)\n\t}\n\tln, err := net.Listen(\"unix\", addr)\n\tif err != nil {\n\t\treturn err\n\t}\n\tif err = os.Chmod(addr, mode); err != nil {\n\t\t// Close the listener so the unix socket file descriptor is not\n\t\t// leaked when chmod fails before Serve takes ownership of it.\n\t\t_ = ln.Close()\n\t\treturn fmt.Errorf(\"cannot chmod %#o for %q: %w\", mode, addr, err)\n\t}\n\treturn s.Serve(ln)\n}\n\n// ListenAndServeTLS serves HTTPS requests from the given TCP4 addr.\n//\n// certFile and keyFile are paths to TLS certificate and key files.\n//","sourceCodeStart":1768,"sourceCodeEnd":1804,"githubUrl":"https://github.com/valyala/fasthttp/blob/c96f600972c6f4a7a30d664257b340ebe9d60124/server.go#L1768-L1804","documentation":"Returned by Server.ListenAndServeUNIX when it attempts to remove a pre-existing file at the unix socket path before binding, and os.Remove fails with an error other than not-exist. The server deletes any stale socket file first so it can bind cleanly; an unremovable file blocks startup.","triggerScenarios":"The path at addr exists and cannot be removed: it is a directory, permission is denied on the parent directory, or the file is owned by another user without write access to the directory. Any os.Remove error that is not ENOENT triggers this.","commonSituations":"Stale socket left by a previous run under a different user/UID (e.g. container ran as root previously, now as non-root); socket path placed in a read-only or root-owned directory; a regular directory accidentally configured as the unix socket path.","solutions":["Manually remove the stale socket file (rm /path/to.sock) or fix its permissions so the server user can delete it.","Run the server with a user that has write+execute permission on the socket's parent directory.","Move the socket path to an app-owned directory (e.g. /run/myapp/app.sock with proper tmpfiles.d setup).","Ensure the path is not a directory and previous instances ran under the same UID."],"exampleFix":"// before\napp.ListenAndServeUNIX(\"/var/run/app.sock\", 0o600) // /var/run is root-only\n// after\nos.MkdirAll(\"/run/app\", 0o755)\napp.ListenAndServeUNIX(\"/run/app/app.sock\", 0o600)","handlingStrategy":"try-catch","validationCode":"// Before ListenAndServeUNIX, check the path is removable\nif fi, err := os.Lstat(addr); err == nil {\n    if fi.IsDir() { log.Fatalf(\"%s is a directory\", addr) }\n    if err := os.Remove(addr); err != nil && !os.IsNotExist(err) {\n        log.Fatalf(\"cannot remove stale socket %s: %v\", addr, err)\n    }\n}","typeGuard":null,"tryCatchPattern":"err := app.ListenAndServeUNIX(sockPath, 0o600)\nif err != nil && strings.Contains(err.Error(), \"remove unix socket\") {\n    log.Fatalf(\"fix permissions on %s or remove stale socket: %v\", filepath.Dir(sockPath), err)\n}","preventionTips":["Place unix sockets in an app-owned directory with consistent run UID.","Clean up stale sockets on shutdown (defer os.Remove(sockPath)).","Avoid running the same socket path under different UIDs (e.g. root in dev, app user in prod).","Never configure a directory as the socket path."],"tags":["go","unix-socket","filesystem-permissions"],"backgroundTag":"unix-socket-remove-failed","analyzedSha":"c96f600972c6f4a7a30d664257b340ebe9d60124","analyzedAt":"2026-08-31T22:48:28.265Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}