"nomad" is a reserved top-level directory path, but you may

Error message

"nomad" is a reserved top-level directory path, but you may write variables to "nomad/jobs", "nomad/job-templates", "nomad/sentinel", or below

What it means

ValidatePath rejects a variable path of exactly "nomad": that top-level directory is reserved. Variables may be written under nomad/jobs, nomad/job-templates, nomad/sentinel, or deeper subpaths, but not at the root.

Source

Thrown at nomad/structs/variables.go:429

}

func ValidatePath(path string) error {
	if len(path) == 0 {
		return fmt.Errorf("variable requires path")
	}
	if !validVariablePath.MatchString(path) {
		return fmt.Errorf("invalid path %q", path)
	}

	parts := strings.Split(path, "/")

	if parts[0] != "nomad" {
		return nil
	}

	// Don't allow a variable with path "nomad"
	if len(parts) == 1 {
		return fmt.Errorf(`"nomad" is a reserved top-level directory path, but you may write variables to "nomad/jobs", "nomad/job-templates", "nomad/sentinel", or below`)
	}

	switch {
	case parts[1] == "jobs" || parts[1] == "sentinel":
		// Any path including "nomad/jobs" or "nomad/sentinel" is valid
		return nil
	case parts[1] == "job-templates" && len(parts) == 3:
		// Paths including "nomad/job-templates" is valid, provided they have single further path part
		return nil
	case parts[1] == "job-templates":
		// Disallow exactly nomad/job-templates with no further paths
		return fmt.Errorf("\"nomad/job-templates\" is a reserved directory path, but you may write variables at the level below it, for example, \"nomad/job-templates/template-name\"")
	default:
		// Disallow arbitrary sub-paths beneath nomad/
		return fmt.Errorf("only paths at \"nomad/jobs\" or \"nomad/job-templates\" and below are valid paths under the top-level \"nomad\" directory")
	}
}

View on GitHub (pinned to 482b49bf1a)

Solutions

Write the variable under "nomad/jobs/..." or another allowed subdirectory
Choose a non-reserved top-level path outside the nomad namespace

Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at nomad/structs/variables.go:429 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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