What causes "port already in use: %w" in kataras/iris?

Stop the other process listening on the socket (lsof/fuser the socket path) or kill the duplicate instance.

port already in use: %w

Error message

port already in use: %w

What it means

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.

Source

Thrown at core/netutil/tcp.go:76

	// 	ln, err = TCP(addr)
	// }

	ln, err = TCP(addr, reuse)
	if err != nil {
		return nil, err
	}
	return tcpKeepAliveListener{ln.(*net.TCPListener), keepAliveDur}, nil
}

// UNIX returns a new unix(file) Listener.
func UNIX(socketFile string, mode os.FileMode) (net.Listener, error) {
	if errOs := os.Remove(socketFile); errOs != nil && !os.IsNotExist(errOs) {
		return nil, fmt.Errorf("%s: %w", socketFile, errOs)
	}

	l, err := net.Listen("unix", socketFile)
	if err != nil {
		return nil, fmt.Errorf("port already in use: %w", err)
	}

	if err = os.Chmod(socketFile, mode); err != nil {
		return nil, fmt.Errorf("cannot chmod %#o for %q: %w", mode, socketFile, err)
	}

	return l, nil
}

// TLS returns a new TLS Listener and an error on failure.
func TLS(addr, certFile, keyFile string) (net.Listener, error) {
	if certFile == "" || keyFile == "" {
		return nil, errors.New("empty certFile or KeyFile")
	}

	cert, err := tls.LoadX509KeyPair(certFile, keyFile)
	if err != nil {
		return nil, err

View on GitHub (pinned to 7bedaf55a0)

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.

Example fix

// before
ln, _ := netutil.UNIX("/run/app.sock", 0666) // in use
// after
if _, err := os.Stat("/run/app.sock"); err == nil {
    os.Remove("/run/app.sock") // only if no live listener
}
ln, _ := netutil.UNIX("/run/app.sock", 0666)

Defensive patterns

Strategy: retry

Validate before calling

if fi, err := os.Stat(socketFile); err == nil {
    // check if a live process still listens before removing
    conn, err := net.Dial("unix", socketFile)
    if err == nil { conn.Close(); return errors.New("socket in use") }
    os.Remove(socketFile)
}

Try / catch

ln, err := netutil.UNIX(socketFile, mode)
if err != nil && strings.Contains(err.Error(), "port already in use") {
    // stop the duplicate instance or pick a new path, then retry once
    ln, err = netutil.UNIX(socketFile+".2", mode)
}

Prevention

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

When it happens

Trigger: 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.

Common situations: Duplicate deployment; supervisor restarting without killing the old process; systemd socket activation conflict; leftover socket whose owner process still runs.

Related errors

AI-assisted analysis of kataras/iris@7bedaf55a0 (2026-08-30). Data as JSON: /api/errors/657be6b8b018e674. Report an issue: GitHub.