What causes "failed to parse HCL file %s: %w" in hashicorp/nomad?

Run hclfmt (or hcl2 linter) on the file — it reports the syntax error location

failed to parse HCL file %s: %w

Error message

failed to parse HCL file %s: %w

What it means

After decoding, ParseConfigFile re-parses the file with hcl.Parse to manually extract multiple 'vault' blocks (which lack labels). If the HCL text itself has a syntax error, hcl.Parse fails and the error is wrapped as 'failed to parse HCL file <path>'.

Source

Thrown at command/agent/config_parse.go:81

		RPC:       &RPCConfig{},
		Audit:     &config.AuditConfig{},
		Consuls:   []*config.ConsulConfig{},
		Autopilot: &config.AutopilotConfig{},
		Telemetry: &Telemetry{},
		Vaults:    []*config.VaultConfig{},
		Reporting: config.DefaultReporting(),
	}

	err = hcl.Decode(c, buf.String())
	if err != nil {
		return nil, fmt.Errorf("failed to decode HCL file %s: %w", path, err)
	}

	// Re-parse the file to extract the multiple Vault configurations, which we
	// need to parse by hand because we don't have a label on the block
	root, err := hcl.Parse(buf.String())
	if err != nil {
		return nil, fmt.Errorf("failed to parse HCL file %s: %w", path, err)
	}
	list, ok := root.Node.(*ast.ObjectList)
	if !ok {
		return nil, fmt.Errorf("error parsing: root should be an object")
	}
	matches := list.Filter("vault")
	if len(matches.Items) > 0 {
		if err := parseVaults(c, matches); err != nil {
			return nil, fmt.Errorf("error parsing 'vault': %w", err)
		}
	}
	matches = list.Filter("consul")
	if len(matches.Items) > 0 {
		if err := parseConsuls(c, matches); err != nil {
			return nil, fmt.Errorf("error parsing 'consul': %w", err)
		}
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

Run hclfmt (or hcl2 linter) on the file — it reports the syntax error location
Check for unbalanced braces/brackets and missing commas around the reported line
Inspect the file for merge-conflict markers or truncation from failed deploys
Regenerate the file from a known-good template

Example fix

// before
service {
  name = "web"
// missing closing brace
// after
service {
  name = "web"
}

Defensive patterns

Strategy: validation

Validate before calling

src, err := os.ReadFile(path)
if err != nil { return err }
if _, err := hcl.Parse(string(src)); err != nil {
    return fmt.Errorf("HCL syntax pre-check failed for %s: %w", path, err)
}

Try / catch

if _, err := hcl.Parse(string(src)); err != nil {
    if pos := errPos(err); pos != nil {
        return fmt.Errorf("syntax error at line %d: %w", pos.Line, err)
    }
    return err
}

Prevention

Run hclfmt as a pre-commit hook — it catches syntax errors early
Check for unbalanced braces after hand edits or merge conflicts
Reject merge-conflict markers in config via CI grep
Regenerate templated configs and diff against last-known-good

When it happens

Trigger: Any HCL syntax error in the config file: unbalanced braces/brackets, missing commas or newlines between assignments, invalid tokens, or truncated files.

Common situations: Hand-edited .hcl files with unbalanced braces, merge conflicts left in config files, templating that emitted invalid HCL, or copy-paste dropping closing braces.

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

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