hashicorp/nomad · error

failed to parse policy: %w

Error message

failed to parse policy: %w

What it means

This error is returned when hcl.Parse fails on the raw ACL policy rules string in acl/policy.go. It wraps the underlying HCL syntax error with %w, so the root cause (line/column of the syntax error) is preserved. This happens before any semantic validation of the policy.

Source

Thrown at acl/policy.go:755

		}
	}()

	if err = hcl.Decode(p, rules); err != nil {
		return err
	}

	// Manually parse the policy to fix blocks without labels.
	//
	// Due to a bug in the way HCL decodes files, a block without a label may
	// return an incorrect key value and make it impossible to determine if the
	// key was set by the user or incorrectly set by the decoder.
	//
	// By manually parsing the file we are able to determine if the label is
	// missing in the file and set them to an empty string so the policy
	// validation can return the appropriate errors.
	root, err := hcl.Parse(rules)
	if err != nil {
		return fmt.Errorf("failed to parse policy: %w", err)
	}

	list, ok := root.Node.(*ast.ObjectList)
	if !ok {
		return errors.New("error parsing: root should be an object")
	}

	nsList := list.Filter("namespace")
	for i, nsObj := range nsList.Items {
		// Fix missing namespace key.
		if len(nsObj.Keys) == 0 {
			p.Namespaces[i].Name = ""
		}
		if i > 0 {
			p.removeExtraKey("namespace")
		}

		// Fix missing variable paths.

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped HCL error for the exact line/column and fix the syntax in the policy file.
2. Run the rules through an HCL linter or `hcltools`/validator before applying.
3. If the policy should be JSON, ensure it uses valid HCL-parseable syntax (HCL is a superset of JSON, so check braces/commas).

Example fix

// before (invalid HCL)
key_prefix "foo" {
  policy = read
// after
key_prefix "foo" {
  policy = "read"
}

// pre-parse the rules to catch HCL syntax errors early
if _, err := hclparse.Parser{}.ParseHCL([]byte(rules), "policy.hcl"); err != nil {
    return fmt.Errorf("policy has HCL syntax errors: %w", err)
}

// handle wrapped hcl errors with errors.As
_, err := parsePolicy(rules)
var hclErr *hcl.Diagnostic
if errors.As(err, &hclErr) {
    log.Printf("fix policy syntax: %v", hclErr)
}

When it happens

Trigger: Passing syntactically invalid HCL to acl policy parsing — unbalanced braces, missing quotes, invalid tokens, or non-HCL content in policy rules (e.g. from `consul acl policy create/update` with a bad -rules file, or agent config with malformed policy).

Common situations: Typos in HCL policy files; shell heredocs mangling quotes; JSON policy files accidentally saved with HCL syntax or vice versa; editors inserting smart quotes.

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

• Invalid quota policy: %#v
• Invalid plugin policy: %#v
• invalid acl policy: %v
• no one-time token returned
• no ACL token returned

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