GoogleContainerTools/skaffold · error

unknown port-forward option %q: expected: user, services, po

Error message

unknown port-forward option %q: expected: user, services, pods, debug, off

What it means

validateMode rejects any --port-forward value that is neither a boolean literal nor one of the recognized named modes (off, user, services, pods, debug). The library throws this so typos in mode names fail fast instead of silently not forwarding.

Source

Thrown at pkg/skaffold/config/portforward.go:186

			return err
		}
		// Boolean values (true/false/1/0) and `off` must be used alone.
		if _, err := strconv.ParseBool(mode); len(modes) > 1 && (err == nil || mode == off) {
			return fmt.Errorf("port-forward %q cannot be combined with other options", mode)
		}
	}
	return nil
}

func validateMode(mode string) error {
	if _, err := strconv.ParseBool(mode); err == nil {
		return nil
	}
	switch mode {
	case off, user, services, pods, debug:
		return nil
	default:
		return fmt.Errorf("unknown port-forward option %q: expected: user, services, pods, debug, off", mode)
	}
}

func (p PortForwardOptions) ForwardUser(runMode RunMode) bool {
	// When --port-forward was a boolean option, user-defined port-forwards
	// were enabled all modes.
	return p.forwardUser || p.compat
}

func (p PortForwardOptions) ForwardServices(runMode RunMode) bool {
	// When --port-forward was a boolean option, service forwarding
	// was enabled all modes.
	return p.forwardServices || p.compat
}

func (p PortForwardOptions) ForwardPods(runMode RunMode) bool {
	// Compatibility break: when `--port-forward` was a boolean option,
	// all pods containerPorts were forwarded for `debug`.  But now we

View on GitHub (pinned to a1189de023)

Solutions

1. Use an exact valid mode: user, services, pods, debug, or off
2. Fix casing — values are lowercase and case-sensitive
3. Check `skaffold help` or docs for the current --port-forward syntax

Example fix

// before
--port-forward=pod
// after
--port-forward=pods

var validModes = map[string]bool{"off":true,"user":true,"services":true,"pods":true,"debug":true}
func checkModes(v string) error {
  for _, m := range strings.Split(v, ",") {
    if _, err := strconv.ParseBool(m); err == nil || validModes[m] { continue }
    return fmt.Errorf("invalid port-forward mode %q", m)
  }
  return nil
}

func isKnownPortForwardMode(m string) bool {
  switch m {
  case "off", "user", "services", "pods", "debug":
    return true
  }
  _, err := strconv.ParseBool(m)
  return err == nil
}

if err := opts.Append(mode); err != nil {
  if strings.Contains(err.Error(), "unknown port-forward option") {
    return fmt.Errorf("%w; valid modes: user, services, pods, debug, off", err)
  }
  return err
}

When it happens

Trigger: Calling Append/Replace (via validateModes) with a mode string that fails strconv.ParseBool and is not exactly one of off/user/services/pods/debug, e.g. `--port-forward=pod`, `--port-forward=Users`, `--port-forward=service`.

Common situations: Typos or pluralization mistakes in the flag value; copying flags from old docs or blog posts that predate the named-mode syntax; case sensitivity surprises (`Pods` vs `pods`).

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• port-forward %q cannot be combined with other options
• portForward[%d] of config with name '%s' is empty, Please ch
• %s is not a valid resource type for port forwarding
• `apply` requires at least one manifest argument
• `exec` requires exactly one action to execute

AI-assisted analysis of GoogleContainerTools/skaffold@a1189de023 (2026-09-05). Data as JSON: /api/errors/040d27e165a48b14. Report an issue: GitHub.