istio/istio · error

bootstrap requires pod name or --file parameter

Error message

bootstrap requires pod name or --file parameter

What it means

Thrown by `istioctl proxy-config bootstrap` when the argument/file precondition fails: the command requires exactly one of a pod name argument OR `--file <envoy-config.json>`, not both and not neither. The Args hook enforces `(len(args) == 1) != (configDumpFile == "")` — i.e. exactly one source of Envoy config must be given.

Source

Thrown at istioctl/pkg/proxyconfig/proxyconfig.go:1135

		Long:  `Retrieve information about bootstrap configuration for the Envoy instance in the specified pod.`,
		Example: `  # Retrieve full bootstrap configuration for a given pod from Envoy.
  istioctl proxy-config bootstrap <pod-name[.namespace]>

  # Retrieve full bootstrap configuration for a pod under a deployment from Envoy.
  istioctl proxy-config bootstrap deployment/<deployment-name[.namespace]>

  # Retrieve full bootstrap without using Kubernetes API
  ssh <user@hostname> 'curl localhost:15000/config_dump' > envoy-config.json
  istioctl proxy-config bootstrap --file envoy-config.json

  # Show a human-readable Istio and Envoy version summary
  istioctl proxy-config bootstrap <pod-name[.namespace]> -o short
`,
		Aliases: []string{"b"},
		Args: func(cmd *cobra.Command, args []string) error {
			if (len(args) == 1) != (configDumpFile == "") {
				cmd.Println(cmd.UsageString())
				return fmt.Errorf("bootstrap requires pod name or --file parameter")
			}
			return nil
		},
		RunE: func(c *cobra.Command, args []string) error {
			var configWriter *configdump.ConfigWriter
			kubeClient, err := ctx.CLIClient()
			if err != nil {
				return err
			}
			if len(args) == 1 {
				if podName, podNamespace, err = getPodName(ctx, args[0]); err != nil {
					return err
				}
				configWriter, err = setupPodConfigdumpWriter(kubeClient, podName, podNamespace, bootstrapPath, c.OutOrStdout())
			} else {
				configWriter, err = setupFileConfigdumpWriter(configDumpFile, c.OutOrStdout())
			}
			if err != nil {

View on GitHub (pinned to 8dc789c5cf)

Solutions

1. Pass exactly one source: `istioctl proxy-config bootstrap <pod>.<namespace>` or `istioctl proxy-config bootstrap --file envoy-config.json`.
2. If both were given, remove either the pod argument or the `--file` flag.
3. Check quoting of arguments if a script may expand to multiple words.

Example fix

# before (neither, or both)
istioctl proxy-config bootstrap
istioctl proxy-config bootstrap mypod --file dump.json

# after
istioctl proxy-config bootstrap mypod.default

# bash: enforce XOR before invoking
if [ $# -eq 1 ] && [ -n "$DUMP_FILE" ]; then echo 'pass pod XOR --file, not both' >&2; exit 2; fi
if [ $# -eq 0 ] && [ -z "$DUMP_FILE" ]; then echo 'need pod or --file' >&2; exit 2; fi

When it happens

Trigger: Running `istioctl proxy-config bootstrap` with no args and no `--file`; or with both a pod name and `--file`; or with two positional args (len(args)==2 makes the XOR false).

Common situations: Forgetting `--file` when working offline from a dumped config; passing both a pod and a file because you assumed file overrides the pod; shell globbing producing extra positional args.

Related errors

• secret requires pod name or --file parameter
• rootca-compare requires 2 pods as an argument
• ecds requires pod name or --file parameter
• error: you must specify resources by --filename. Example res
• metrics requires workload name

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