What causes "invalid socks port %d" in lima-vm/lima?

Use an unprivileged port, e.g. `--socks-port 1080`

invalid socks port %d

Error message

invalid socks port %d

What it means

The SOCKS listener port given via `--socks-port` must be an ephemeral port (0 = auto-pick) or an unprivileged port in 1024–65535. Ports below 1024 (privileged) are rejected by this check before the tunnel starts.

Source

Thrown at cmd/limactl/tunnel.go:65

	return tunnelCmd
}

func tunnelAction(cmd *cobra.Command, args []string) error {
	ctx := cmd.Context()
	flags := cmd.Flags()
	tunnelType, err := flags.GetString("type")
	if err != nil {
		return err
	}
	if tunnelType != "socks" {
		return fmt.Errorf("unknown tunnel type: %#q", tunnelType)
	}
	port, err := flags.GetInt("socks-port")
	if err != nil {
		return err
	}
	if port != 0 && (port < 1024 || port > 65535) {
		return fmt.Errorf("invalid socks port %d", port)
	}
	stdout, stderr := cmd.OutOrStdout(), cmd.ErrOrStderr()
	instName := args[0]
	inst, err := store.Inspect(ctx, instName)
	if err != nil {
		if errors.Is(err, os.ErrNotExist) {
			return fmt.Errorf("instance %#q does not exist, run `limactl create %s` to create a new instance", instName, instName)
		}
		return err
	}
	if inst.Status == limatype.StatusStopped {
		return fmt.Errorf("instance %#q is stopped, run `limactl start %s` to start the instance", instName, instName)
	}

	if port == 0 {
		port, err = freeport.TCP()
		if err != nil {
			return err

View on GitHub (pinned to dd909d0973)

Solutions

Use an unprivileged port, e.g. `--socks-port 1080`
Omit `--socks-port` (or pass 0) to let Lima pick a free port automatically
Run as root only if you truly must bind a privileged port (not supported by this flag check)

Example fix

// before
limactl tunnel --socks-port 808 myinstance   # still <1024
// after
limactl tunnel --socks-port 1080 myinstance

Defensive patterns

Strategy: validation

Validate before calling

port, _ := strconv.Atoi(socksPort)
if port != 0 && (port < 1024 || port > 65535) {
	return fmt.Errorf("socks port %d out of range; use 0 (auto) or 1024-65535", port)
}

Prevention

Use ports >= 1024 for the SOCKS listener
Pass 0 or omit --socks-port to auto-select a free port
Never hardcode well-known ports (<1024) for local proxies

When it happens

Trigger: Running `limactl tunnel --socks-port 80` or `--socks-port 443` (or any value <1024 other than 0), or a value above 65535 if the flag parsing allows it.

Common situations: Trying to reuse a well-known port for the local SOCKS proxy; port assumptions from other proxy tools; scripting that passes a service port instead of a free local port.

Related errors

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/88b1713d92d4f3cc. Report an issue: GitHub.