istio/istio · error

only one of name, --selector, or --revision can be specified

Error message

only one of name, --selector, or --revision can be specified

What it means

Mutual-exclusion check in 'istioctl dashboard controlz'. The condition (selector AND name) OR (selector AND revision) OR (name AND revision) means any two of the three pod-selection inputs supplied together abort the command after printing usage. Only one of name, --selector, --revision may be used.

Source

Thrown at istioctl/pkg/dashboard/dashboard.go:355

  # Open ControlZ web UI for the istiod-56dd66799-jfdvs pod in a custom namespace
  istioctl dashboard controlz istiod-56dd66799-jfdvs -n custom-ns

  # Open ControlZ web UI for any Istiod pod
  istioctl dashboard controlz deployment/istiod.istio-system

  # with short syntax
  istioctl dash controlz istiod-56dd66799-jfdvs.istio-system
  istioctl d controlz istiod-56dd66799-jfdvs.istio-system
`,
		RunE: func(c *cobra.Command, args []string) error {
			if labelSelector == "" && opts.Revision == "" && len(args) < 1 {
				c.Println(c.UsageString())
				return fmt.Errorf("specify a pod, --selector, or --revision")
			}

			if (labelSelector != "" && len(args) > 0) || (labelSelector != "" && opts.Revision != "") || (len(args) > 0 && opts.Revision != "") {
				c.Println(c.UsageString())
				return fmt.Errorf("only one of name, --selector, or --revision can be specified")
			}

			client, err := ctx.CLIClientWithRevision(opts.Revision)
			if err != nil {
				return fmt.Errorf("failed to create k8s client: %v", err)
			}

			if opts.Revision != "" {
				labelSelector = "istio.io/rev=" + opts.Revision + ", app=istiod"
			}
			var podName, ns string
			if labelSelector != "" {
				labelSelector += ", app=istiod"
				pl, err := client.PodsForSelector(context.TODO(), ctx.NamespaceOrDefault(ctx.IstioNamespace()), labelSelector)
				if err != nil {
					return fmt.Errorf("not able to locate pod with selector %s: %v", labelSelector, err)
				}

View on GitHub (pinned to 8dc789c5cf)

Solutions

1. Remove all but one selection mechanism — keep the name, the selector, or the revision
2. If you need revision pinning, drop the pod name and use only --revision
3. Audit wrappers/aliases that unconditionally set --revision

Example fix

# before
istioctl dashboard controlz istiod-56dd66799-jfdvs --revision default

# after
istioctl dashboard controlz istiod-56dd66799-jfdvs
# or
istioctl dashboard controlz --revision default

# enforce mutual exclusion in wrappers
count=0; [ $# -ge 1 ] && count=$((count+1)); [ -n "$SELECTOR" ] && count=$((count+1)); [ -n "$REVISION" ] && count=$((count+1))
[ "$count" -eq 1 ] || { echo "exactly one of name/--selector/--revision" >&2; exit 2; }

When it happens

Trigger: 'istioctl dashboard controlz istiod-xyz --revision default', or '... --selector app=istiod --revision canary', or '... istiod-xyz --selector app=istiod'.

Common situations: Scripts defaulting --revision to a value while also passing a pod name; users adding --revision 'just to be safe'; upgrading from older istioctl versions that ignored extra flags.

Related errors

• specify a pod, --selector, or --revision
• name cannot be provided when a selector is specified
• unknown dashboard %q
• expecting pod name
• unknown resource type %q

AI-assisted analysis of istio/istio@8dc789c5cf (2026-08-15). Data as JSON: /api/errors/4adb68fc1fcd6070. Report an issue: GitHub.