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

VarPutCommand.validateOutputFlag rejects -template when -output is not go-template (allowed non-template formats: none, json, hcl, table). The template flag only applies to go-template rendering, so mismatched combinations fail fast.

Source

Thrown at command/var_put.go:601

		c.inFmt = "hcl"
	default:
		return fmt.Errorf("Unable to determine format of %s; Use the -in flag to specify it.", arg)
	}
	return nil
}

func (c *VarPutCommand) validateInputFlag() error {
	switch c.inFmt {
	case "hcl", "json":
		return nil
	default:
		return errors.New(errInvalidInFormat)
	}
}

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

func warnInvalidIdentifier(in string) error {
	invalid := invalidIdentifier.FindAllString(in, -1)
	if len(invalid) == 0 {
		return nil

View on GitHub (pinned to 482b49bf1a)

Solutions

Remove -template when using json/hcl/none/table output
Or set -output=go-template with a valid template
Post-process json output with jq instead of templating

Example fix

// before
vault kv put -in=hcl -output=json -template='{{ .Data }}' secret/foo @spec.hcl
// after
vault kv put -in=hcl -output=json secret/foo @spec.hcl

Defensive patterns

Strategy: validation

Validate before calling

if outFmt != "go-template" && tmpl != "" {
	return fmt.Errorf("-template requires -output=go-template, got %q", outFmt)
}
switch outFmt {
case "none", "json", "hcl", "table", "go-template":
	// ok
default:
	return fmt.Errorf("invalid -out %q", outFmt)
}

Try / catch

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

Prevention

Pass -template only with -output=go-template
Avoid unconditional flag injection in shared scripts
Add combination tests for flag pairs in CI

When it happens

Trigger: Running `vault kv put -template=... -output=json|hcl|none|table ...` (c.outFmt != go-template and c.tmpl != "").

Common situations: Shared scripts that always append -template; switching put output to json for automation while the template flag remains; copy-paste from a get command that used go-template.

Related errors

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