hashicorp/nomad · error

format must be key=value

Error message

format must be key=value

What it means

Each KVBuilder argument must contain exactly one '=' separating key and value (len(parts) == 2 after splitting on '='). Arguments with zero or more than two '=' segments fail with this error. Bare keys, empty strings, and values containing '=' (since strings.Split is used) are all rejected.

Source

Thrown at command/var.go:233

			b.stdin = true
			return b.addReader(b.Stdin)
		}

		// If the arg begins with "@" then we need to read a file directly
		if raw[0] == '@' {
			f, err := os.Open(raw[1:])
			if err != nil {
				return err
			}
			defer f.Close()

			return b.addReader(f)
		}
	}

	if len(parts) != 2 {
		return fmt.Errorf("format must be key=value")
	}
	key, value := parts[0], parts[1]

	if len(value) > 0 {
		if value[0] == '@' {
			contents, err := os.ReadFile(value[1:])
			if err != nil {
				return fmt.Errorf("error reading file: %w", err)
			}

			value = string(contents)
		} else if value[0] == '\\' && value[1] == '@' {
			value = value[1:]
		} else if value == "-" {
			if b.Stdin == nil {
				return fmt.Errorf("stdin is not supported")
			}
			if b.stdin {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Provide the argument as exactly 'key=value': -var feature_flag=true
2. Quote arguments in the shell so '=' is not lost to word splitting: -var 'key=value'
3. Note values containing '=' (e.g. base64) may exceed 2 parts — use a '@file' reference or stdin ('key=-') for such values instead

Example fix

// before
-var mykey
// after
-var mykey=myvalue

for _, a := range args {
	if a == "-" { continue }
	if strings.Count(a, "=") != 1 {
		return fmt.Errorf("var arg %q must be key=value", a)
	}
}

When it happens

Trigger: Calling KVBuilder.Add with 'key' (no '='), an empty string, or 'a=b=c' (three parts). On the CLI: -var mykey or -var a=b=c.

Common situations: Users forgetting the value: '-var feature_flag'; shell word-splitting dropping the '=value' half; attempts to embed '=' in values without understanding the parser splits on every '='.

Related errors

• invalid key/value pair %q: %w
• Invalid key value pair for topic: %s
• stdin already consumed
• error reading file: %w
• not a terminal

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