freeport.VSock is not implemented for non-Windows hosts

Error message

freeport.VSock is not implemented for non-Windows hosts

What it means

On non-Windows hosts freeport.VSock() is a stub that always returns this error, because vsock (AF_VSOCK) port probing is only implemented for Windows hosts in this codebase. Callers (e.g. Lima instance setup) hit it when the vsock-based free-port discovery path is taken on macOS or Linux.

Source

Thrown at pkg/freeport/freeport_unix.go:11

//go:build !windows

// SPDX-FileCopyrightText: Copyright The Lima Authors
// SPDX-License-Identifier: Apache-2.0

package freeport

import "errors"

func VSock() (int, error) {
	return 0, errors.New("freeport.VSock is not implemented for non-Windows hosts")
}

View on GitHub (pinned to dd909d0973)

Solutions

Only call freeport.VSock() when runtime.GOOS == "windows"; use TCP()/UDP() elsewhere.
Gate the feature that needs a vsock port on host OS, and skip or stub it on non-Windows.
If vsock probing is genuinely needed on Linux/macOS, implement a platform-specific VSock() (e.g. bind to an AF_VSOCK socket on port 0).

Example fix

// before
port, err := freeport.VSock()
// after
var port int
var err error
if runtime.GOOS == "windows" {
    port, err = freeport.VSock()
} else {
    port, err = freeport.TCP()
}

Defensive patterns

Strategy: validation

Validate before calling

if runtime.GOOS != "windows" {
    return errors.New("vsock port probing is only available on Windows hosts")
}

Type guard

func vsockSupported() bool { return runtime.GOOS == "windows" }

Try / catch

if !vsockSupported() {
    // use TCP()/UDP() fallback
    port, err = freeport.TCP()
} else {
    port, err = freeport.VSock()
}

Prevention

Always gate freeport.VSock() behind runtime.GOOS == "windows"
Use build tags for platform-specific port allocation code
Add a unit test asserting VSock() is only exercised on Windows

When it happens

Trigger: Calling freeport.VSock() directly, or driving the Lima instance-creation path (New) that consults VSock() for a free vsock port, on any host where runtime.GOOS != "windows".

Common situations: Running Lima code paths that expect the Windows vsock port allocator on a macOS or Linux host; tests or tooling invoking VSock() unconditionally instead of guarding on GOOS.

Related errors

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