istio/istio · error

--output must be 'yaml' or 'json'

Error message

--output must be 'yaml' or 'json'

What it means

The `istioctl version` command validates its `--output` flag and only accepts 'yaml' or 'json' (plus default human-readable when empty). Any other value is rejected with this error before any version info is printed. Simple CLI argument validation.

Source

Thrown at pkg/version/cobra.go:72

}

// CobraCommandWithOptions returns a command used to print version information.
// It accepts an CobraOptions argument that might modify its behavior
func CobraCommandWithOptions(options CobraOptions) *cobra.Command {
	var (
		short         bool
		output        string
		remote        bool
		version       Version
		remoteVersion *MeshInfo
	)

	cmd := &cobra.Command{
		Use:   "version",
		Short: "Prints out build version information",
		RunE: func(cmd *cobra.Command, args []string) error {
			if output != "" && output != "yaml" && output != "json" {
				return errors.New(`--output must be 'yaml' or 'json'`)
			}

			version.ClientVersion = &Info

			if options.GetRemoteVersion != nil && remote {
				remoteVersion, _ = options.GetRemoteVersion()
				version.MeshVersion = remoteVersion
			}
			if options.GetProxyVersions != nil && remote {
				version.DataPlaneVersion, _ = options.GetProxyVersions()
			}

			switch output {
			case "":
				if short {
					_, _ = fmt.Fprintf(cmd.OutOrStdout(), "client version: %s\n", version.ClientVersion.Version)
					if remoteVersion != nil {
						remoteVersion = coalesceVersions(remoteVersion)

View on GitHub (pinned to 8dc789c5cf)

Solutions

1. Use `--output yaml` or `--output json` (or the shorthand `-o yaml`/`-o json`).
2. Omit the flag entirely for the default human-readable summary.
3. In scripts, default the variable: `OUTPUT=${OUTPUT:-json}`.

Example fix

# before
istioctl version -o wide

# after
istioctl version
# or
istioctl version -o json

outFlag := os.Getenv("ISTIOCTL_OUTPUT")
if outFlag != "" && outFlag != "yaml" && outFlag != "json" {
    outFlag = "json"
}

Not applicable — validate the flag before invoking istioctl; on non-zero exit, print the error and re-run with a supported value.

When it happens

Trigger: Running `istioctl version -o wide`, `-o table`, `-o NAME`, or any typo like `--output=jason`; also scripts that pass an unset shell variable that expands to garbage.

Common situations: Muscle memory from kubectl (`-o wide`/`-o jsonpath=...`); CI scripts assuming kubectl-compatible output formats; shell variable that is empty-but-quoted oddly or misspelled.

Related errors

• (%s is experimental. Use `istioctl experimental %s`)
• filename not specified (see --filename or -f)
• invalid level option
• expected a resource
• unable to find any Istiod instances

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