lima-vm/lima · error

invalid port forward format %#q, expected HOST:GUEST

Error message

invalid port forward format %#q, expected HOST:GUEST

What it means

Thrown by `ParsePortForward` when the first comma-separated segment of the port-forward spec does not split into exactly two `:`-separated parts. The HOST:GUEST portion must contain exactly one colon; zero or multiple colons (e.g. an IPv6 literal, or `8080` alone) fail with the offending segment quoted via `%#q`.

Source

Thrown at cmd/limactl/editflags/editflags.go:147

	flags.String("audio-device", "", commentPrefix+"Audio device backend (e.g., 'pa', 'coreaudio', 'none')")
	flags.String("audio-interface", "", commentPrefix+"Audio virtual hardware interface ('hda' or 'virtio')")
}

func defaultExprFunc(expr string) func(v *flag.Flag) ([]string, error) {
	return func(v *flag.Flag) ([]string, error) {
		return []string{fmt.Sprintf(expr, v.Value)}, nil
	}
}

func ParsePortForward(spec string) (hostPort, guestPort string, isStatic bool, err error) {
	parts := strings.Split(spec, ",")
	if len(parts) > 2 {
		return "", "", false, fmt.Errorf("invalid port forward format %#q, expected HOST:GUEST or HOST:GUEST,static=true", spec)
	}

	portParts := strings.Split(strings.TrimSpace(parts[0]), ":")
	if len(portParts) != 2 {
		return "", "", false, fmt.Errorf("invalid port forward format %#q, expected HOST:GUEST", parts[0])
	}

	hostPort = strings.TrimSpace(portParts[0])
	guestPort = strings.TrimSpace(portParts[1])

	if len(parts) == 2 {
		staticPart := strings.TrimSpace(parts[1])
		if staticValue, ok := strings.CutPrefix(staticPart, "static="); ok {
			isStatic, err = strconv.ParseBool(staticValue)
			if err != nil {
				return "", "", false, fmt.Errorf("invalid value for static parameter: %#q", staticValue)
			}
		} else {
			return "", "", false, fmt.Errorf("invalid parameter %#q, expected `static=` followed by a boolean value", staticPart)
		}
	}

	return hostPort, guestPort, isStatic, nil

View on GitHub (pinned to dd909d0973)

Solutions

1. Provide both sides: `HOST:GUEST`, e.g. `8080:80` or `127.0.0.1:8080:80` -> use just `8080:80`.
2. For an IPv6 host address, bracket it so the split is unambiguous — if still unsupported by the flag, configure it in the YAML `portForwards` with `hostIP` instead.
3. To forward a specific host interface/IP, edit `portForwards[].hostIP` in the instance YAML rather than embedding the IP in this flag's spec.
4. Trim whitespace and ensure exactly one colon in the first segment before the comma.

Example fix

// before
limactl edit myvm --port-forward '8080'            // missing :GUEST
limactl edit myvm --port-forward '127.0.0.1:8080:80' // too many colons

// after
limactl edit myvm --port-forward '8080:80'

// Ensure the HOST:GUEST part has exactly one colon before invoking:
first := strings.SplitN(spec, ",", 2)[0]
if strings.Count(strings.TrimSpace(first), ":") != 1 {
    return fmt.Errorf("HOST:GUEST must have exactly one colon, got %q", first)
}

if err := runCmd("limactl", "edit", inst, "--port-forward", spec); err != nil {
    if strings.Contains(err.Error(), "expected HOST:GUEST") {
        return fmt.Errorf("spec segment %q must be exactly HOST:GUEST with one colon", strings.SplitN(spec, ",", 2)[0])
    }
    return err
}

When it happens

Trigger: Passing specs like `8080` (missing guest port), `127.0.0.1:8080:80` (host address with port plus a second colon) or `::1:8080` (unbracketed IPv6) to `limactl edit --port-forward` / `BuildPortForwardExpression`.

Common situations: Users supplying only a single port expecting lima to mirror it; trying to forward for a specific host IP (not supported by this flag); IPv6 hosts pasted unbracketed; whitespace typos.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• invalid port forward format %#q, expected HOST:GUEST or HOST
• invalid value for static parameter: %#q
• invalid parameter %#q, expected `static=` followed by a bool
• disk format %#q not supported, use `qcow2` or `raw` instead
• the YAML is invalid, attempted to save the buffer as %#q but

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