{"record":{"id":"52e6574f927ee666","repo":"hashicorp/nomad","slug":"failed-to-reattach-to-plugin-because-supported-api","errorCode":null,"errorMessage":"failed to reattach to plugin because supported API versions for the plugin and Nomad do not overlap","messagePattern":"failed to reattach to plugin because supported API versions for the plugin and Nomad do not overlap","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/pluginutils/loader/loader.go","lineNumber":276,"sourceCode":"\tif apiVersion != \"\" {\n\t\tinstance.apiVersion = apiVersion\n\t} else {\n\t\t// We do not know the API version since we are reattaching, so discover\n\t\t// it\n\t\tbplugin := raw.(base.BasePlugin)\n\n\t\t// Retrieve base plugin information\n\t\ti, err := bplugin.PluginInfo()\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to get plugin info for plugin: %v\", err)\n\t\t}\n\n\t\tapiVersion, err := l.selectApiVersion(i)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to validate API versions %v for plugin %s: %v\", i.PluginApiVersions, i.Name, err)\n\t\t}\n\t\tif apiVersion == \"\" {\n\t\t\treturn nil, fmt.Errorf(\"failed to reattach to plugin because supported API versions for the plugin and Nomad do not overlap\")\n\t\t}\n\n\t\tinstance.apiVersion = apiVersion\n\t}\n\n\treturn instance, nil\n}\n\n// getPluginMap returns a plugin map based on the type of plugin being launched.\nfunc getPluginMap(pluginType string, logger log.Logger) map[string]plugin.Plugin {\n\tpmap := map[string]plugin.Plugin{\n\t\tbase.PluginTypeBase: &base.PluginBase{},\n\t}\n\n\tswitch pluginType {\n\tcase base.PluginTypeDevice:\n\t\tpmap[base.PluginTypeDevice] = &device.PluginDevice{}\n\tcase base.PluginTypeDriver:","sourceCodeStart":258,"sourceCodeEnd":294,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/pluginutils/loader/loader.go#L258-L294","documentation":"Version negotiation in dispensePlugin returned an empty string, meaning the sets of API versions supported by the plugin and by Nomad do not intersect. The loader refuses to continue since no common protocol version exists.","triggerScenarios":"loader.Reattach (or Dispense) to an existing plugin whose PluginApiVersions share no entry with Nomad's supported API versions.","commonSituations":"Nomad upgraded or downgraded past what the installed plugin supports; reattaching to a stale plugin process left over from a previous Nomad version.","solutions":["Restart the Nomad agent so a fresh, compatible plugin is launched instead of reattaching","Upgrade the plugin to a version supporting Nomad's current API versions","Align Nomad and plugin versions (both built for the same plugin API generation)"],"exampleFix":"// before: nomad 0.11 reattaching to old docker logging plugin with only v0 API\n// after: upgrade the plugin binary in plugin_dir to one supporting v1, then restart agent","handlingStrategy":"retry","validationCode":"// before reattach, check plugin API version overlap\nsupported := map[string]bool{\"v1\": true}\noverlap := false\nfor _, v := range info.PluginApiVersions { if supported[v] { overlap = true } }\nif !overlap { return fmt.Errorf(\"plugin %s incompatible with this Nomad\", info.Name) }","typeGuard":null,"tryCatchPattern":"inst, err := loader.Reattach(...)\nif err != nil {\n    if strings.Contains(err.Error(), \"do not overlap\") {\n        // force a fresh launch instead of reattach\n        os.Remove(reattachConfigPath)\n        inst, err = loader.Dispense(...)\n    }\n}","preventionTips":["Restart Nomad agents after version upgrades to avoid stale reattach configs","Pin plugin versions alongside Nomad versions in deployment tooling","Remove stale reattach files on upgrade"],"tags":["plugin-loader","api-version","reattach"],"backgroundTag":"plugin-api-version-mismatch","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"}