istio/istio · error

expecting a WorkloadGroup artifact file or the name and name

Error message

expecting a WorkloadGroup artifact file or the name and namespace of an existing WorkloadGroup

What it means

Args validator of `istioctl x workload entry configure` (istioctl/pkg/workload/workload.go:217). The command needs either a local WorkloadGroup artifact (-f) or both --name and --namespace to fetch one from the API server; if filename is empty and either name or namespace is empty it aborts with this error before touching the cluster.

Source

Thrown at istioctl/pkg/workload/workload.go:217

}

func configureCommand(ctx cli.Context) *cobra.Command {
	var opts clioptions.ControlPlaneOptions

	configureCmd := &cobra.Command{
		Use:   "configure",
		Short: "Generates all the required configuration files for a workload instance running on a VM or non-Kubernetes environment",
		Long: `Generates all the required configuration files for workload instance on a VM or non-Kubernetes environment from a WorkloadGroup artifact.
This includes a MeshConfig resource, the cluster.env file, and necessary certificates and security tokens.
Configure requires either the WorkloadGroup artifact path or its location on the API server.`,
		Example: `  # configure example using a local WorkloadGroup artifact
  istioctl x workload entry configure -f workloadgroup.yaml -o config

  # configure example using the API server
  istioctl x workload entry configure --name foo --namespace bar -o config`,
		Args: func(cmd *cobra.Command, args []string) error {
			if filename == "" && (name == "" || namespace == "") {
				return fmt.Errorf("expecting a WorkloadGroup artifact file or the name and namespace of an existing WorkloadGroup")
			}
			if outputDir == "" {
				return fmt.Errorf("expecting an output directory")
			}
			return nil
		},
		RunE: func(cmd *cobra.Command, args []string) error {
			kubeClient, err := ctx.CLIClientWithRevision(ctx.RevisionOrDefault(opts.Revision))
			if err != nil {
				return err
			}

			wg := &clientnetworking.WorkloadGroup{}
			if filename != "" {
				if err := readWorkloadGroup(filename, wg); err != nil {
					return err
				}
			} else {

View on GitHub (pinned to 8dc789c5cf)

Solutions

1. Provide the artifact: `istioctl x workload entry configure -f workloadgroup.yaml -o config`
2. Or provide full identity: `istioctl x workload entry configure --name foo --namespace bar -o config`
3. If using the API server path, double-check BOTH --name and -n are set
4. Verify the artifact file exists on this machine before running

Example fix

# before
istioctl x workload entry configure -o config
# after
istioctl x workload entry configure -f workloadgroup.yaml -o config

if [ -z "$FILE" ] && { [ -z "$WG_NAME" ] || [ -z "$WG_NS" ]; }; then
  echo "need -f <file> OR both --name and --namespace" >&2; exit 2
fi

When it happens

Trigger: `istioctl x workload entry configure -o config` alone; `configure --name foo -o config` (namespace missing); `configure -f missing-and-no-name` (empty -f combined with partial identity flags).

Common situations: Operators configuring VMs who forget the file was never copied onto the VM; scripts where only one of name/namespace is parameterized; example commands copy-pasted without the -f or --name/--namespace part.

Related errors

• expecting a workload name
• expecting a workload namespace
• expecting an output directory
• the flags --internalIP and --externalIP are mutually exclusi
• must specify a waypoint name or delete all using --all or de

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