hashicorp/nomad · error

unable to parse var file: %v

Error message

unable to parse var file: %v

What it means

During variable decoding, each file in config.VarFiles is parsed as HCL or JSON. If parsing a var file yields no body or HCL diagnostics contain errors, decode aborts with 'unable to parse var file: <diagnostics>'. The wrapped message carries the actual HCL syntax/type error.

Source

Thrown at jobspec2/parse.go:140

	// parsedVarFiles represent parsed HCL AST of the passed EnvVars
	parsedVarFiles []*hcl.File
}

func (c *ParseConfig) normalize() {
	if c.BaseDir == "" {
		c.BaseDir = filepath.Dir(c.Path)
	}
}

func decode(c *jobConfig) error {
	config := c.ParseConfig

	file, diags := parseHCLOrJSON(config.Body, config.Path)

	for _, varFile := range config.VarFiles {
		parsedVarFile, ds := parseFile(varFile)
		if parsedVarFile == nil || ds.HasErrors() {
			return fmt.Errorf("unable to parse var file: %v", ds.Error())
		}

		config.parsedVarFiles = append(config.parsedVarFiles, parsedVarFile)
		diags = append(diags, ds...)
	}

	if config.VarContent != "" {
		hclFile, hclDiagnostics := parseHCLOrJSON([]byte(config.VarContent), "input.hcl")
		if hclDiagnostics.HasErrors() {
			return fmt.Errorf("unable to parse var content: %v", hclDiagnostics.Error())
		}
		config.parsedVarFiles = append(config.parsedVarFiles, hclFile)
	}

	// Return early if the input job or variable files are not valid.
	// Decoding and evaluating invalid files may result in unexpected results.
	if diags.HasErrors() {
		return diags

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix the syntax error reported in the wrapped HCL diagnostics for that var file.
2. Verify the file exists, is readable, and is valid HCL or JSON (validate with hclfmt or a JSON linter).
3. Convert non-HCL/JSON files (YAML, TOML, env-style) to HCL or JSON before use.
4. Re-encode the file as plain UTF-8 without BOM and retry.

Example fix

// before (vars.yaml passed as var file)
-var-file=vars.yaml

// after (convert to valid HCL)
// vars.hcl
key = "value"

for _, f := range varFiles {
    data, err := os.ReadFile(f)
    if err != nil { return fmt.Errorf("var file unreadable: %s: %w", f, err) }
    if err := hclwrite.Format(data); err != nil && json.Valid(data) == false {
        return fmt.Errorf("var file is not valid HCL/JSON: %s", f)
    }
}

if err := ParseWithConfig(cfg); err != nil {
    var pe *parseErr
    if strings.HasPrefix(err.Error(), "unable to parse var file") {
        // surface the wrapped diagnostics to the user
    }
}

When it happens

Trigger: Calling ParseWithConfig/parseWithConfigImpl where a VarFiles entry is unreadable, malformed HCL/JSON, empty, or of the wrong format so parseFile returns nil or diagnostics with errors.

Common situations: Typo or syntax error in a .hcl/.json var file; passing a YAML or TOML file; passing a directory or nonexistent path; file saved with wrong extension; BOM or encoding issues.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• unable to parse var content: %v
• <combined HCL diagnostics from str.String()>
• Failed to read var file(s): %w
• Failed to parse ACL Policy: %v
• failed to parse HCL file %s: %w

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