{"record":{"id":"58e05989fdb01e66","repo":"hashicorp/nomad","slug":"parsing-plugin-configurations-failed-v","errorCode":null,"errorMessage":"parsing plugin configurations failed: %v","messagePattern":"parsing plugin configurations failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/pluginutils/loader/init.go","lineNumber":85,"sourceCode":"\t// Scan for eligibile binaries\n\tplugins, err := l.scan()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to scan plugin directory %q: %v\", l.pluginDir, err)\n\t}\n\n\t// Fingerprint the passed plugins\n\texternal, err := l.fingerprintPlugins(plugins, configMap)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to fingerprint plugins: %v\", err)\n\t}\n\n\t// Merge external and internal plugins\n\tl.plugins = l.mergePlugins(internal, external)\n\n\t// Validate that the configs are valid for the plugins\n\tcanonicalizedConfigs, err := l.validatePluginConfigs()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"parsing plugin configurations failed: %v\", err)\n\t}\n\n\tfor i := range configMap {\n\t\tif updated, ok := canonicalizedConfigs[i]; ok {\n\t\t\tconfigMap[i].Config = updated.Config\n\t\t}\n\t}\n\n\treturn configMap, nil\n}\n\n// initInternal initializes internal plugins.\nfunc (l *PluginLoader) initInternal(plugins map[PluginID]*InternalPluginConfig, configs map[string]*config.PluginConfig) (map[PluginID]*pluginInfo, error) {\n\tctx, cancel := context.WithCancel(context.Background())\n\tdefer cancel()\n\n\tvar mErr multierror.Error\n\tfingerprinted := make(map[PluginID]*pluginInfo, len(plugins))","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/pluginutils/loader/init.go#L67-L103","documentation":"After merging internal and external plugins, validatePluginConfigs decodes and canonicalizes each plugin's HCL configuration against the plugin's own config spec. Errors from that parsing/validation are wrapped with this message and returned by NewPluginLoader.","triggerScenarios":"A plugin's config map contains keys the plugin doesn't recognize, values of the wrong type (string where an int is expected), or malformed HCL that cannot be decoded into the plugin's config struct.","commonSituations":"Hand-written HCL config with typos in option names; config copied from an older plugin version whose schema changed; passing environment-specific values (e.g. a string port) that the plugin expects as numbers; nested blocks supplied where only flat options are supported.","solutions":["Read the wrapped inner error to identify the offending plugin and config key.","Fix the option names/types in the plugin's config to match the plugin's documented schema.","Run the plugin standalone with `plugin -config <file>` (where supported) to validate config before loading.","If you upgraded a plugin, migrate its config to the new schema."],"exampleFix":"// before\n// plugin config hcl\nconfig {\n  \"endpoint\" = \"unix:///var/run/docker.sock\"\n  \"retries\" = \"3\"   # string where int expected\n}\n\n// after\nconfig {\n  endpoint = \"unix:///var/run/docker.sock\"\n  retries  = 3\n}","handlingStrategy":"validation","validationCode":"for _, c := range cfg.Configs {\n    if err := validateAgainstPluginSchema(c.Name, c.Config); err != nil {\n        return fmt.Errorf(\"plugin %q config invalid: %w\", c.Name, err)\n    }\n}","typeGuard":null,"tryCatchPattern":"loader, err := NewPluginLoader(cfg)\nif err != nil {\n    if strings.Contains(err.Error(), \"parsing plugin configurations failed\") {\n        return fmt.Errorf(\"fix plugin HCL config per error detail: %w\", err)\n    }\n    return err\n}","preventionTips":["Keep plugin config templates in sync with the plugin version's schema.","Lint HCL config files before deployment.","When upgrading plugins, review the plugin's config-schema changelog and migrate configs.","Use typed config structs at the edge and decode once, early."],"tags":["go","configuration","hcl","plugins"],"backgroundTag":"schema-validation-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}