{"record":{"id":"efe60eecd517aa5f","repo":"hashicorp/nomad","slug":"unknown-plugin-with-name-q-and-type-q","errorCode":null,"errorMessage":"unknown plugin with name %q and type %q","messagePattern":"unknown plugin with name %q and type %q","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/pluginutils/loader/loader.go","lineNumber":170,"sourceCode":"\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) {\n\tid := PluginID{\n\t\tName:       name,\n\t\tPluginType: pluginType,\n\t}\n\tpinfo, ok := l.plugins[id]\n\tif !ok {\n\t\treturn nil, fmt.Errorf(\"unknown plugin with name %q and type %q\", name, pluginType)\n\t}\n\n\t// If the plugin is internal, launch via the factory\n\tvar instance PluginInstance\n\tif pinfo.factory != nil {\n\t\tctx, cancel := context.WithCancel(context.Background())\n\t\tinstance = &internalPluginInstance{\n\t\t\tinstance:   pinfo.factory(ctx, logger),\n\t\t\tapiVersion: pinfo.apiVersion,\n\t\t\tkillFn:     cancel,\n\t\t}\n\t} else {\n\t\tvar err error\n\t\tinstance, err = l.dispensePlugin(pinfo.baseInfo.Type, pinfo.apiVersion, pinfo.exePath, pinfo.args, nil, logger)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to launch plugin: %v\", err)\n\t\t}\n\t}","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/pluginutils/loader/loader.go#L152-L188","documentation":"Dispense looks up a plugin instance by PluginID{Name, PluginType} in the loader's plugins map; if absent it returns this error. It means the named plugin was never registered — it was not found in the plugin dir, its config stanza names a plugin that doesn't exist, or the loader wasn't initialized with it.","triggerScenarios":"Calling Dispense (e.g. from validatePluginConfig during agent startup) with a name/pluginType pair that has no entry in l.plugins — typically a `plugin \"name\" { type = ... }` stanza in the agent config referencing an uninstalled plugin.","commonSituations":"Typo in the plugin name in the agent config stanza; plugin binary not present in plugin_dir; wrong `type` field (e.g. \"driver\" vs actual registered type); agent config copied from another host without installing the plugin.","solutions":["Ensure the plugin stanza's name matches the plugin binary filename in plugin_dir exactly.","Verify the plugin binary exists and is executable in the configured plugin_dir.","Check the pluginType argument matches the type the plugin registers (task driver vs device, etc.).","Restart agent config discovery: confirm the loader init logs list the plugin as discovered.","Install the missing plugin or remove the stanza from the agent config."],"exampleFix":"// before (agent config)\nplugin \"dockerd\" {\n  config { ... }   # no such plugin installed\n}\n// after (correct binary name)\nplugin \"docker\" {\n  config { ... }\n}","handlingStrategy":"validation","validationCode":"// Before writing a plugin stanza, confirm the plugin is discoverable:\nids := []loader.PluginID{} // from loader introspection/logs at startup\nfunc pluginInstalled(name, ptype string, dir string) bool {\n    _, err := os.Stat(filepath.Join(dir, name))\n    return err == nil\n}\nif !pluginInstalled(\"docker\", \"driver\", cfg.PluginDir) {\n    return errors.New(\"plugin stanza references uninstalled plugin\")\n}","typeGuard":null,"tryCatchPattern":"inst, err := l.Dispense(name, ptype, agentCfg, logger)\nif err != nil && strings.Contains(err.Error(), \"unknown plugin\") {\n    return fmt.Errorf(\"plugin %q (%s) not found in %s; install it or fix the stanza\", name, ptype, cfg.PluginDir)\n}","preventionTips":["Match stanza names exactly to plugin binary filenames","Install plugins on every host before referencing them in agent config","Use config validation tooling to catch unknown plugins pre-start"],"tags":["plugin-loader","unknown-plugin","plugin-discovery","nomad"],"backgroundTag":"unknown-plugin","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"}