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

VarListCommand.validateOutputFlag rejects the -template flag when the -output format is not go-template. Templates only apply to go-template rendering, so combining them with json/terse/table output is a user error caught before execution.

Source

Thrown at command/var_list.go:292

		if ns == "*" {
			return fmt.Sprintf("%s|%s", v.Namespace, v.Path)
		}
		return v.Path
	}

	// Reduce the items slice to a string slice containing only the
	// variable paths.
	pList := make([]string, len(vars))
	for i, sv := range vars {
		pList[i] = toPathStr(sv)
	}

	return pList
}

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

View on GitHub (pinned to 482b49bf1a)

Solutions

Remove the -template flag when output is json/terse/table
Or set -output=go-template so the template is honored
Post-process json/terse output with jq or similar instead

Example fix

// before
vault kv list -output=terse -template='{{ range . }}{{ . }}{{ end }}' secret/
// after
vault kv list -output=terse secret/

Defensive patterns

Strategy: validation

Validate before calling

if outFmt != "go-template" && tmpl != "" {
	return fmt.Errorf("-template requires -output=go-template, got %q", outFmt)
}

Try / catch

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

Prevention

Strip -template when switching list output to json/terse/table
Use distinct wrapper functions per output format
Test flag combinations in CI

When it happens

Trigger: Running `vault kv list -template=... -output=json|terse|table <path>` (c.outFmt != go-template and c.tmpl != "").

Common situations: Reusing a shared command-line wrapper that always sets -template; switching a list command from go-template to terse output for scripting but leaving the template flag behind.

Related errors

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