kovidgoyal/kitty · error

Invalid socket address: %s must be prefix by a protocol such

Error message

Invalid socket address: %s must be prefix by a protocol such as unix:

What it means

ParseSocketAddress expects socket specs of the form network:address (e.g. unix:/path/to/sock, tcp:127.0.0.1:8080). It uses strings.Cut on the first ':'; if no colon is present the spec cannot be split into network and address and this error is returned, hinting that a protocol prefix is required.

Source

Thrown at tools/utils/sockets.go:17

// License: GPLv3 Copyright: 2022, Kovid Goyal, <kovid at kovidgoyal.net>

package utils

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)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Prefix the spec with a network: unix:/run/app.sock, tcp:0.0.0.0:8080, fd:3.
2. Update the config/CLI default and docs to the network:address form.
3. Validate specs with strings.Contains(spec, ":") before startup.

Example fix

// before
net, addr, err := utils.ParseSocketAddress("/run/kitty.sock")
// after
net, addr, err := utils.ParseSocketAddress("unix:/run/kitty.sock")

if !strings.Contains(spec, ":") {
    return fmt.Errorf("socket spec %q needs a network prefix like unix:", spec)
}

func isSocketSpec(s string) bool {
    _, _, ok := strings.Cut(s, ":")
    return ok
}

net, addr, err := utils.ParseSocketAddress(spec)
if err != nil && strings.Contains(err.Error(), "must be prefix by a protocol") {
    spec = "unix:" + spec
    net, addr, err = utils.ParseSocketAddress(spec)
}

When it happens

Trigger: Passing a bare path like "/run/app.sock" or "localhost:8080" without a leading network type — note that "localhost:8080" would parse network="localhost" and hit the unknown-network error instead; the colon-less case is things like "app.sock".

Common situations: CLI/config values for listen addresses written without the protocol prefix; porting configs from tools that accept bare paths; setup_global_options parsing --listen argument.

Related errors

• Unknown network type: %#v in socket address: %s
• Invalid listen-on value: {spec} must be of the form protocol
• Abstract UNIX sockets are only supported on Linux. Cannot us
• 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/86e69cfc19c7b5ed. Report an issue: GitHub.