{"record":{"id":"04d64e9c2195801d","repo":"hashicorp/nomad","slug":"failed-to-validate-api-versions-v-for-plugin-s-04d64e","errorCode":null,"errorMessage":"failed to validate API versions %v for plugin %s: %v","messagePattern":"failed to validate API versions (.+?) for plugin (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/pluginutils/loader/loader.go","lineNumber":273,"sourceCode":"\t\tinstance: raw,\n\t}\n\n\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 {","sourceCodeStart":255,"sourceCodeEnd":291,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/pluginutils/loader/loader.go#L255-L291","documentation":"After getting plugin info, the loader calls selectApiVersion to negotiate an API version between the versions the plugin supports and those Nomad supports. If negotiation returns an error (inconsistent version lists), the loader wraps it as 'failed to validate API versions ... for plugin <name>'.","triggerScenarios":"loader.Dispense/Reattach where l.selectApiVersion(i) errors, e.g. the plugin declares malformed or empty PluginApiVersions.","commonSituations":"A plugin built for a different Nomad version declaring API versions Nomad cannot validate, or a plugin emitting an empty/duplicated API version set.","solutions":["Read the wrapped error to see why validation failed","Upgrade or downgrade the plugin so its PluginApiVersions match Nomad's supported set","Verify the plugin's PluginInfo() returns well-formed, non-empty PluginApiVersions"],"exampleFix":"// before: plugin reports PluginApiVersions: []string{} \n// after: rebuild plugin so it registers e.g. []string{\"v1\"}","handlingStrategy":"validation","validationCode":"// validate plugin info before relying on dispense\n// (server side ensure PluginApiVersions non-empty and known)\nif len(info.PluginApiVersions) == 0 { return fmt.Errorf(\"plugin declares no API versions\") }","typeGuard":null,"tryCatchPattern":"inst, err := loader.Dispense(name, ptype, cfg, logger)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to validate API versions\") {\n        logger.Error(\"plugin API version negotiation failed\", \"err\", err)\n    }\n    return err\n}","preventionTips":["Keep plugins and Nomad on compatible release lines","After upgrades, restart agents so plugins are re-launched, not reattached","Verify plugin PluginInfo output in a unit test"],"tags":["plugin-loader","api-version","version-mismatch"],"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"}