GoogleContainerTools/skaffold · error

port-forward %q cannot be combined with other options

Error message

port-forward %q cannot be combined with other options

What it means

skaffold's --port-forward option accepts multiple named modes (user, services, pods, debug), but boolean values (true/false/1/0) and the legacy value `off` are only meaningful when used alone. validateModes throws this error when such a value appears together with other modes, because the combination is ambiguous (e.g. 'pods,off' cannot express a consistent intent).

Source

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

		}
		b, err := strconv.ParseBool(o)
		if err == nil && !b {
			return false
		}
	}
	return true
}

// validateModes checks that the given set of port-forward modes are ok.
// For example, `off` and boolean values should not be combined with other values.
func validateModes(modes []string) error {
	for _, mode := range modes {
		if err := validateMode(mode); err != nil {
			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 {

View on GitHub (pinned to a1189de023)

Solutions

1. Remove the boolean/`off` value and keep only named modes, e.g. `--port-forward=user,services`
2. If forwarding should be disabled, use `--port-forward=off` alone (or omit the flag)
3. Update stale scripts/aliases written for the boolean-era flag syntax

Example fix

// before
--port-forward=pods,true
// after
--port-forward=pods

func validPortForwardFlag(v string) error {
  modes := strings.Split(v, ",")
  boolish := func(m string) bool { _, err := strconv.ParseBool(m); return err == nil || m == "off" }
  if len(modes) > 1 {
    for _, m := range modes {
      if boolish(m) {
        return fmt.Errorf("port-forward %q cannot be combined with other options", m)
      }
    }
  }
  return nil
}

func isBooleanOrOff(m string) bool {
  if m == "off" { return true }
  _, err := strconv.ParseBool(m)
  return err == nil
}

if err := opts.Append(flagValue); err != nil {
  if strings.Contains(err.Error(), "cannot be combined") {
    log.Warn("boolean/off must be used alone; using default named modes")
    err = opts.Replace("user")
  }
  return err
}

When it happens

Trigger: Calling Append/Replace/Set on PortForwardOptions with a mode list of length > 1 containing a strconv.ParseBool-parseable value (true/false/1/0/t/f) or the literal `off`, e.g. `--port-forward=pods,true` or `--port-forward=off,user`.

Common situations: Users upgrading from older skaffold where --port-forward was purely boolean keep an old `--port-forward=true` alongside newly added named modes in scripts, shell aliases, or skaffold.yaml profiles; CI pipelines concatenating flags produce `--port-forward=user,off`.

Related errors

• unknown port-forward option %q: expected: user, services, po
• 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/793c7835ac0e94fc. Report an issue: GitHub.