semaphoreui/semaphore · error

listening on socket

Error message

listening on socket %q: %w

What it means

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.

Solutions

1. 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
2. Ensure the socket's parent directory exists and is writable by the Semaphore process user
3. Keep the socket path short — Unix sockets fail with 'invalid argument' when the path exceeds roughly 104-108 bytes
4. If another agent instance is genuinely running on that socket, stop it or configure a distinct socket path per instance

When it happens

Trigger: Thrown at pkg/ssh/agent.go:74 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of semaphoreui/semaphore@1774ccb71a (2026-09-07). Data as JSON: /api/errors/096334d6db6d07ff. Report an issue: GitHub.

Appendix: source

Thrown at pkg/ssh/agent.go:74

			PrivateKey: key,
		}); err != nil {
			return fmt.Errorf("adding private key: %w", err)
		}
	}

	if err := os.MkdirAll(path.Dir(a.SocketFile), 0o755); err != nil {
		return fmt.Errorf("creating socket directory: %w", err)
	}

	l, err := net.ListenUnix(
		"unix",
		&net.UnixAddr{
			Net:  "unix",
			Name: a.SocketFile,
		},
	)
	if err != nil {
		return fmt.Errorf("listening on socket %q: %w", a.SocketFile, err)
	}

	l.SetUnlinkOnClose(true)
	a.listener = l
	a.done = make(chan struct{})

	go func() {
		for {
			conn, err := a.listener.Accept()
			if err != nil {
				select {
				case <-a.done:
					return
				default:
					a.Logger.Logf("error accepting socket connection: %w", err)
					return
				}
			}

View on GitHub (pinned to 1774ccb71a)