hashicorp/nomad · error

"%s" contains characters %s that require the 'index' functio

Error message

"%s" contains characters %s that require the 'index' function for direct access in templates

What it means

warnInvalidIdentifier validates variable item keys (and path segments) against the invalidIdentifier regex before templating. Keys containing characters that are not valid in Go template field access (spaces, punctuation beyond the allowed set) cannot be referenced directly as `.Items.myKey`, so the command rejects them with a message listing exactly which characters are problematic.

Source

Thrown at command/var_put.go:623

		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
	}

	// Use %s instead of %q to avoid escaping characters.
	return fmt.Errorf(
		`"%s" contains characters %s that require the 'index' function for direct access in templates`,
		in,
		formatInvalidVarKeyChars(invalid),
	)
}

func formatInvalidVarKeyChars(invalid []string) string {
	// Deduplicate characters
	chars := set.From(invalid)

	// Sort the characters for output
	charList := make([]string, 0, chars.Size())

	for k := range chars.Items() {
		// Use %s instead of %q to avoid escaping characters.
		charList = append(charList, fmt.Sprintf(`"%s"`, k))
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Rename the key using only allowed characters (alphanumerics/underscore), e.g. `my_key` instead of `my key`.
2. Keep the key but access it in templates via the index function: `{{ index .Items "my key" }}` — note the command errors rather than warns, so prefer renaming.
3. Use `nomad var init` output as a reference for valid key formats and update automation/scripts accordingly.

Example fix

// before
nomad var put -path app/config items "my key=value"
// after
nomad var put -path app/config items "my_key=value"

# reject item keys with spaces or template-hostile characters before submission
if echo "$key" | grep -Eq '[^A-Za-z0-9_]'; then
  echo "key '$key' has characters needing index()-based template access; rename it" >&2
  exit 2
fi

var invalidIdentifier = regexp.MustCompile(`[^\w]`) // mirror of the library regex; adapt to the allowed set
func isValidVarKey(k string) bool { return !invalidIdentifier.MatchString(k) }

if err := run(); err != nil && strings.Contains(err.Error(), "require the 'index' function") {
    log.Fatalf("rename the variable key: %v", err)
}

When it happens

Trigger: `nomad var put` with an items key such as `my key`, `my-key`, `a.b`, or `key[0]` — any key containing characters matched by invalidIdentifier — when the key would be used for direct template access. Called from Run during argument/input validation.

Common situations: Encoding config values with spaces in keys; keys copied from other systems using dashes or dots; templating attempts like `{{ .Items.my-key }}` that would fail or misbehave in Go templates.

Related errors

• Missing task name
• Task cannot be named "alloc"
• Task name cannot include slashes
• Task name cannot include null characters
• Service name must be valid per RFC 1123 and can contain only

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