{"record":{"id":"096334d6db6d07ff","repo":"semaphoreui/semaphore","slug":"listening-on-socket-q-w","errorCode":null,"errorMessage":"listening on socket %q: %w","messagePattern":"listening on socket %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/ssh/agent.go","lineNumber":74,"sourceCode":"\t\t\tPrivateKey: key,\n\t\t}); err != nil {\n\t\t\treturn fmt.Errorf(\"adding private key: %w\", err)\n\t\t}\n\t}\n\n\tif err := os.MkdirAll(path.Dir(a.SocketFile), 0o755); err != nil {\n\t\treturn fmt.Errorf(\"creating socket directory: %w\", err)\n\t}\n\n\tl, err := net.ListenUnix(\n\t\t\"unix\",\n\t\t&net.UnixAddr{\n\t\t\tNet:  \"unix\",\n\t\t\tName: a.SocketFile,\n\t\t},\n\t)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"listening on socket %q: %w\", a.SocketFile, err)\n\t}\n\n\tl.SetUnlinkOnClose(true)\n\ta.listener = l\n\ta.done = make(chan struct{})\n\n\tgo func() {\n\t\tfor {\n\t\t\tconn, err := a.listener.Accept()\n\t\t\tif err != nil {\n\t\t\t\tselect {\n\t\t\t\tcase <-a.done:\n\t\t\t\t\treturn\n\t\t\t\tdefault:\n\t\t\t\t\ta.Logger.Logf(\"error accepting socket connection: %w\", err)\n\t\t\t\t\treturn\n\t\t\t\t}\n\t\t\t}","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/semaphoreui/semaphore/blob/1774ccb71a0a8b82eb74ea24c23ac9ab713de2fa/pkg/ssh/agent.go#L56-L92","documentation":"Returned by Agent.Listen in pkg/ssh/agent.go when net.ListenUnix cannot bind the Unix domain socket at the agent socket path. It fires when the path already exists (typically a stale socket left by a previous run), the parent directory is missing or not writable, or the path exceeds the unix socket length limit. The %w wraps the net.OpError with the OS-level bind failure.","triggerScenarios":"Thrown at pkg/ssh/agent.go:74 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Remove the stale socket file at the reported path (a leftover from a crashed run is the most common cause) and retry starting the agent","Ensure the socket's parent directory exists and is writable by the Semaphore process user","Keep the socket path short — Unix sockets fail with 'invalid argument' when the path exceeds roughly 104-108 bytes","If another agent instance is genuinely running on that socket, stop it or configure a distinct socket path per instance"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"1774ccb71a0a8b82eb74ea24c23ac9ab713de2fa","analyzedAt":"2026-09-07T11:00:33.293Z","contentChangedAt":"2026-09-07T11:00:33.293Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}