{"record":{"id":"4b876f8b27ad9df9","repo":"hashicorp/nomad","slug":"failed-to-decode-hcl-file-s-w","errorCode":null,"errorMessage":"failed to decode HCL file %s: %w","messagePattern":"failed to decode HCL file (.+?): %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/agent/config_parse.go","lineNumber":74,"sourceCode":"\t\t},\n\t\tServer: &ServerConfig{\n\t\t\tClientIntroduction:   &ClientIntroduction{},\n\t\t\tPlanRejectionTracker: &PlanRejectionTracker{},\n\t\t\tServerJoin:           &ServerJoin{},\n\t\t},\n\t\tACL:       &ACLConfig{},\n\t\tRPC:       &RPCConfig{},\n\t\tAudit:     &config.AuditConfig{},\n\t\tConsuls:   []*config.ConsulConfig{},\n\t\tAutopilot: &config.AutopilotConfig{},\n\t\tTelemetry: &Telemetry{},\n\t\tVaults:    []*config.VaultConfig{},\n\t\tReporting: config.DefaultReporting(),\n\t}\n\n\terr = hcl.Decode(c, buf.String())\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to decode HCL file %s: %w\", path, err)\n\t}\n\n\t// Re-parse the file to extract the multiple Vault configurations, which we\n\t// need to parse by hand because we don't have a label on the block\n\troot, err := hcl.Parse(buf.String())\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to parse HCL file %s: %w\", path, err)\n\t}\n\tlist, ok := root.Node.(*ast.ObjectList)\n\tif !ok {\n\t\treturn nil, fmt.Errorf(\"error parsing: root should be an object\")\n\t}\n\tmatches := list.Filter(\"vault\")\n\tif len(matches.Items) > 0 {\n\t\tif err := parseVaults(c, matches); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"error parsing 'vault': %w\", err)\n\t\t}\n\t}","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/config_parse.go#L56-L92","documentation":"ParseConfigFile reads the config file and decodes it into a Config struct via hcl.Decode. If HCL decoding fails (valid text but structure/types don't match the Config schema), the error is wrapped as 'failed to decode HCL file <path>'.","triggerScenarios":"A config file whose syntax parses but whose keys/types don't fit the Config struct — e.g. a value where a list is expected, unknown nested blocks, or type mismatches (string vs number) that hcl.Decode rejects.","commonSituations":"Wrong value types (ports as strings vs numbers depending on version), copy-pasted blocks from newer Consul versions into older ones, typos in block/keys causing mapping failures.","solutions":["Read the wrapped %w error — it pinpoints the field/type that failed to decode","Fix the value type to match the expected schema (e.g. numbers for ports, lists for bind addresses arrays)","Check docs for your Consul version — schema differs across versions","Run the file through hclfmt and compare with a known-good example config"],"exampleFix":"// before\nports { http = \"8500\" }  // wrong type\n// after\nports { http = 8500 }","handlingStrategy":"validation","validationCode":"src, err := os.ReadFile(path)\nif err != nil { return err }\nvar probe map[string]interface{}\nif err := hcl.Decode(&probe, string(src)); err != nil {\n    return fmt.Errorf(\"HCL decode pre-check failed: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"cfg, err := agentcfg.ParseConfigFile(path)\nif err != nil {\n    var derr *hcl.Error\n    if errors.As(err, &derr) {\n        return fmt.Errorf(\"fix types/keys near %v\", derr)\n    }\n    return err\n}","preventionTips":["Match key names and value types to the Config schema for your Consul version","Don't copy config blocks between Consul versions without checking docs","Run hclfmt + consul validate in CI","Test configs in a dev agent before production rollout"],"tags":["config","consul","hcl","decoding","schema"],"backgroundTag":"hcl-decode-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}