kovidgoyal/kitty · error

Abstract UNIX sockets are only supported on Linux. Cannot us

Error message

Abstract UNIX sockets are only supported on Linux. Cannot use: %s

What it means

ParseSocketAddress accepts abstract (namespace-free) UNIX sockets written as unix:@name, where the leading '@' marks an abstract socket. These exist only on Linux; on macOS, Windows, or BSD the kernel has no abstract socket namespace, so the spec is rejected with this error.

Source

Thrown at tools/utils/sockets.go:22

import (
	"fmt"
	"runtime"
	"strconv"
	"strings"

	"github.com/seancfoley/ipaddress-go/ipaddr"
)

func ParseSocketAddress(spec string) (network string, addr string, err error) {
	network, addr, found := strings.Cut(spec, ":")
	if !found {
		err = fmt.Errorf("Invalid socket address: %s must be prefix by a protocol such as unix:", spec)
		return
	}
	if network == "unix" {
		if strings.HasPrefix(addr, "@") && runtime.GOOS != "linux" {
			err = fmt.Errorf("Abstract UNIX sockets are only supported on Linux. Cannot use: %s", spec)
		}
		return
	}

	if network == "tcp" || network == "tcp6" || network == "tcp4" {
		host := ipaddr.NewHostName(addr)
		if host.IsAddress() {
			network = "ip"
		}
		return
	}
	if network == "ip" || network == "ip6" || network == "ip4" {
		host := ipaddr.NewHostName(addr)
		if !host.IsAddress() {
			err = fmt.Errorf("Not a valid IP address: %#v. Cannot use: %s", addr, spec)
		}
		return
	}

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. On non-Linux, use a filesystem path socket: unix:/tmp/myapp.sock.
2. Make the socket spec platform-conditional in config (runtime.GOOS check).
3. If abstract sockets are required, run the component on Linux only.
4. Use an env var override per platform for the listen address.

Example fix

// before
spec := "unix:@myapp.sock"
// after
spec := "unix:@myapp.sock"
if runtime.GOOS != "linux" {
    spec = "unix:/tmp/myapp.sock"
}

spec := "unix:@sock"
if strings.HasPrefix(spec[strings.Index(spec, ":")+1:], "@") && runtime.GOOS != "linux" {
    spec = "unix:/tmp/sock"
}

func socketSpecValidForOS(spec string) bool {
    _, addr, _ := strings.Cut(spec, ":")
    return !(strings.HasPrefix(addr, "@") && runtime.GOOS != "linux")
}

net, addr, err := utils.ParseSocketAddress(spec)
if err != nil && strings.Contains(err.Error(), "Abstract UNIX") {
    net, addr, err = utils.ParseSocketAddress("unix:/tmp/" + name + ".sock")
}

When it happens

Trigger: Using unix:@myapp-sock on any non-Linux platform (macOS, Windows, *BSD). Detected at option-parsing time in setup_global_options.

Common situations: Cross-platform config shared between Linux servers and Mac dev machines; configs copied from Linux systemd socket-activation setups.

Related errors

• passwd line has %d colon delimited fields instead of 7
• No user record available for user with UID: %#v
• Invalid socket address: %s must be prefix by a protocol such
• Not a valid IP address: %#v. Cannot use: %s
• Not a valid file descriptor number: %#v. Cannot use: %s

AI-assisted analysis of kovidgoyal/kitty@6d5d0c4406 (2026-08-27). Data as JSON: /api/errors/cd45c9f43820cb0d. Report an issue: GitHub.