lima-vm/lima · error

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

Error message

invalid port forward format %#q, expected HOST:GUEST or HOST:GUEST,static=true

What it means

Thrown by `ParsePortForward` in cmd/limactl/editflags when a port-forward spec supplied for `limactl edit --set` (e.g. via port-forward flags) contains more than one comma-separated segment. The accepted forms are `HOST:GUEST` or `HOST:GUEST,static=true`; anything with two or more commas (three+ parts) is rejected with the full spec quoted via `%#q`.

Source

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

	flags.StringArray("port-forward", nil, commentPrefix+"Port forwards (host:guest), e.g., '8080:80' or '9090:9090,static=true' for static port-forwards")
	_ = cmd.RegisterFlagCompletionFunc("port-forward", func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
		return []string{"8080:80", "3000:3000", "8080:80,static=true"}, cobra.ShellCompDirectiveNoFileComp
	})

	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 {

View on GitHub (pinned to dd909d0973)

Solutions

1. Reduce the spec to at most one comma: `HOST:GUEST` or `HOST:GUEST,static=true`.
2. Move unsupported options (proto, reverse, ignore) into the instance YAML's `portForwards` section via the editor instead of the `--set` spec.
3. Check for accidental double colons or extra commas: `127.0.0.1:8080:80` belongs in YAML config, not the CLI spec.
4. Run `limactl edit --help` to confirm the exact accepted syntax for your lima version.

Example fix

// before
limactl edit myvm --set '.portForwards += ...' --port-forward '8080:80,static=true,proto=tcp'

// after
limactl edit myvm --port-forward '8080:80,static=true'   # proto etc. go in the YAML config

// Validate a port-forward spec before passing it to limactl:
func validPortForwardSpec(spec string) bool {
    parts := strings.Split(spec, ",")
    if len(parts) > 2 { return false }
    return len(strings.Split(strings.TrimSpace(parts[0]), ":")) == 2 &&
           (len(parts) == 1 || parts[1] == "static=true")
}

if err := runCmd("limactl", "edit", inst, "--port-forward", spec); err != nil {
    if strings.Contains(err.Error(), "invalid port forward format") {
        return fmt.Errorf("spec %q rejected: use HOST:GUEST or HOST:GUEST,static=true", spec)
    }
    return err
}

When it happens

Trigger: Calling `BuildPortForwardExpression` (used by `limactl edit --set`) with a spec like `8080:80,static=true,proto=tcp` or `"127.0.0.1:8080:80,static=true"` — i.e. more than one comma — or passing extra options that older/experimental syntax allowed.

Common situations: Users copying port-forward options from lima.yaml (which supports more keys like `proto`, `reverse`, `ignore`) into the CLI spec; accidentally quoting the host:guest as one field; typos adding stray commas.

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
• 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/54b8e15451d9194b. Report an issue: GitHub.