{"record":{"id":"bf25ab9dcc864a10","repo":"hashicorp/nomad","slug":"failed-to-initialize-plugin-loader-v","errorCode":null,"errorMessage":"failed to initialize plugin loader: %v","messagePattern":"failed to initialize plugin loader: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"helper/pluginutils/loader/loader.go","lineNumber":145,"sourceCode":"\tfor pType, versions := range config.SupportedVersions {\n\t\tconverted, err := convertVersions(versions)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tsupportedVersions[pType] = converted\n\t}\n\n\tlogger := config.Logger.Named(\"plugin_loader\").With(\"plugin_dir\", config.PluginDir)\n\tl := &PluginLoader{\n\t\tlogger:            logger,\n\t\tsupportedVersions: supportedVersions,\n\t\tpluginDir:         config.PluginDir,\n\t\tplugins:           make(map[PluginID]*pluginInfo),\n\t}\n\n\tupdatedConfig, err := l.init(config)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to initialize plugin loader: %v\", err)\n\t}\n\n\t// DANGER! Secondary effect of init is that it updates the plugin configs\n\t// in the loader's plugins map with any default values from the plugin schemas.\n\t//  We need to propagate those updated configs back to the agent config\n\t// since the agent will use those to report the plugings configs in the API.\n\tfor i, c := range config.Configs {\n\t\tif updated, ok := updatedConfig[c.Name]; ok {\n\t\t\tconfig.Configs[i] = updated\n\t\t}\n\t}\n\n\treturn l, nil\n}\n\n// Dispense returns a plugin instance, loading it either internally or by\n// launching an external plugin.\nfunc (l *PluginLoader) Dispense(name, pluginType string, config *base.AgentConfig, logger log.Logger) (PluginInstance, error) {","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/pluginutils/loader/loader.go#L127-L163","documentation":"NewPluginLoader calls l.init(config) which scans the plugin directory, launches/factories each plugin to fetch its schema and API version, and applies schema defaults. Any failure in that bootstrap is wrapped as \"failed to initialize plugin loader\". Unlike the config-validation error (1852), this one happens after validation, during actual plugin discovery and handshake.","triggerScenarios":"Calling NewPluginLoader when l.init fails: plugin dir unreadable, a plugin binary fails to launch/handshake, an external plugin's API version is unsupported, or schema/default application errors for a plugin config.","commonSituations":"Misconfigured plugin_dir path or wrong permissions; external plugin binaries missing, non-executable, or built against an incompatible API version; a plugin crashing during startup; duplicate plugin names/types on disk.","solutions":["Read the wrapped %v detail to identify which plugin or step failed.","Verify plugin_dir exists, is readable/executable, and contains the intended plugin binaries.","Check each external plugin's supported API version against the Nomad SupportedVersions list.","Run the plugin binary manually to see if it starts and handshakes correctly.","Update or remove the offending plugin binary from plugin_dir."],"exampleFix":"// before\n$ ls $PLUGIN_DIR\nnomad-docker  # no exec bit\n// after\n$ chmod +x $PLUGIN_DIR/nomad-docker\n$ nomad agent -config agent.hcl","handlingStrategy":"validation","validationCode":"info, err := os.Stat(pluginDir)\nif err != nil || !info.IsDir() {\n    return fmt.Errorf(\"plugin dir missing: %s\", pluginDir)\n}\n// also: check each entry is executable\nents, _ := os.ReadDir(pluginDir)\nfor _, e := range ents {\n    if fi, _ := e.Info(); fi != nil && fi.Mode()&0111 == 0 {\n        log.Warn(\"plugin not executable\", \"file\", e.Name())\n    }\n}","typeGuard":null,"tryCatchPattern":"l, err := loader.NewPluginLoader(cfg)\nif err != nil && strings.Contains(err.Error(), \"failed to initialize plugin loader\") {\n    log.Error(\"plugin discovery failed; check plugin_dir and binaries\", \"cause\", err)\n    return err\n}","preventionTips":["Verify plugin_dir exists with correct permissions before starting the agent","Test-launch every external plugin binary manually after install/upgrade","Match plugin API versions to the agent's SupportedVersions","Watch agent startup logs for per-plugin handshake failures"],"tags":["plugin-loader","plugin-discovery","initialization","nomad"],"backgroundTag":"plugin-initialization-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"}