The '-template' flag is only valid when using 'go-template'

Error message

The '-template' flag is only valid when using 'go-template' formatting

What it means

VarGetCommand.validateOutputFlag rejects the -template flag when the -output format is anything other than go-template. The template only has meaning for go-template rendering, so supplying it with hcl/json/none/table output is treated as a user mistake and fails fast before talking to the server.

Source

Thrown at command/var_get.go:203

	c.Ui.Output(out)

	hint, _ := c.Meta.showUIPath(UIHintContext{
		Command: "var get",
		PathParams: map[string]string{
			"path":      path,
			"namespace": sv.Namespace,
		},
		OpenURL: openURL,
	})
	if hint != "" {
		c.Ui.Warn(hint)
	}
	return 0
}

func (c *VarGetCommand) validateOutputFlag() error {
	if c.outFmt != "go-template" && c.tmpl != "" {
		return errors.New(errUnexpectedTemplate)
	}
	switch c.outFmt {
	case "hcl", "json", "none", "table":
		return nil
	case "go-template": //noop - needs more validation
		if c.tmpl == "" {
			return errors.New(errMissingTemplate)
		}
		return nil
	default:
		return errors.New(errInvalidOutFormat)
	}
}

func (c *VarGetCommand) GetConcurrentUI() cli.ConcurrentUi {
	return cli.ConcurrentUi{Ui: c.Ui}
}

View on GitHub (pinned to 482b49bf1a)

Solutions

Remove the -template flag when using a non-go-template -output
Or change -output to go-template so the template is used
For structured output, drop the template and post-process JSON/HCL instead

Example fix

// before
vault kv get -output=json -template='{{ .Data.data }}' secret/foo
// after
vault kv get -output=json secret/foo | jq -r '.data.data'

Defensive patterns

Strategy: validation

Validate before calling

valid := []string{"go-template","hcl","json","none","table"}
if outFmt != "go-template" && tmpl != "" {
	return fmt.Errorf("-template requires -output=go-template, got %q", outFmt)
}
if !slices.Contains(valid, outFmt) {
	return fmt.Errorf("invalid -output %q", outFmt)
}

Try / catch

if err := cmd.validateOutputFlag(); err != nil {
	if strings.Contains(err.Error(), "'-template' flag is only valid") {
		// drop -template or switch to go-template and retry
	}
	return err
}

Prevention

Only pass -template together with -output=go-template
Lint shell wrappers that add flags unconditionally
Validate flag combinations in CI by running commands with -h or dry parsing

When it happens

Trigger: Running `vault kv get -template=... -output=hcl|json|none|table <path>` (or setting c.tmpl while c.outFmt is not go-template).

Common situations: Copy-pasting a command line that previously used -template and switching -output to json for scripting; automation scripts that always pass -template regardless of format.

Related errors

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/de2b9f063b17a085. Report an issue: GitHub.