{"record":{"id":"ee473374f067eaa0","repo":"hashicorp/nomad","slug":"failed-to-validate-api-versions-v-for-plugin-s","errorCode":null,"errorMessage":"failed to validate API versions %v for plugin %s (%v): %v","messagePattern":"failed to validate API versions (.+?) for plugin (.+?) \\((.+?)\\): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/pluginutils/loader/init.go","lineNumber":390,"sourceCode":"\t// Retrieve base plugin information\n\ti, err := bplugin.PluginInfo()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to get plugin info for plugin %q: %v\", info.exePath, err)\n\t}\n\tinfo.baseInfo = i\n\n\t// Parse and set the plugin version\n\tv, err := version.NewVersion(i.PluginVersion)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to parse plugin %q (%v) version %q: %v\",\n\t\t\ti.Name, info.exePath, i.PluginVersion, err)\n\t}\n\tinfo.version = v\n\n\t// Detect the plugin API version to use\n\tav, err := l.selectApiVersion(i)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to validate API versions %v for plugin %s (%v): %v\", i.PluginApiVersions, i.Name, info.exePath, err)\n\t}\n\tif av == \"\" {\n\t\tl.logger.Warn(\"skipping plugin because supported API versions for plugin and Nomad do not overlap\", \"plugin\", i.Name, \"path\", info.exePath)\n\t\treturn nil, nil\n\t}\n\tinfo.apiVersion = av\n\n\t// Retrieve the schema\n\tschema, err := bplugin.ConfigSchema()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to get plugin config schema for plugin %q: %v\", info.exePath, err)\n\t}\n\tinfo.configSchema = schema\n\n\treturn info, nil\n}\n\n// mergePlugins merges internal and external plugins, preferring the highest","sourceCodeStart":372,"sourceCodeEnd":408,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/pluginutils/loader/init.go#L372-L408","documentation":"fingerprintPlugin() calls selectApiVersion(i) to negotiate a common plugin API version between the versions the plugin supports (PluginApiVersions) and the versions the Nomad agent supports. This error is returned when that negotiation function fails (e.g. unrecognized API version labels), wrapping the underlying error with the plugin's advertised versions, name, and exe path. Note: an empty overlap is NOT this error — it only logs a warning and skips the plugin.","triggerScenarios":"l.selectApiVersion(i) returns an error during fingerprintPlugins: the plugin advertises PluginApiVersions entries the agent's negotiation logic cannot resolve/match against its supported set (incompatible or malformed API version labels).","commonSituations":"Plugin built for a newer/older Nomad plugin API than the agent supports; plugin advertises version strings the installed agent doesn't recognize; Nomad upgraded without rebuilding plugins (or vice versa).","solutions":["Check the wrapped %v error and compare the plugin's PluginApiVersions with those supported by your Nomad version.","Rebuild the plugin against the helper/pluginutils/base API versions supported by your Nomad release.","Upgrade Nomad (or the plugin) so the supported API version sets overlap.","Pin matching Nomad and plugin releases from the same release train.","If the plugin cannot be made compatible, remove it; overlap-less plugins are skipped with a warning instead."],"exampleFix":"// before (plugin advertising unsupported API version)\nPluginApiVersions: []string{\"v9.9.9\"}\n// after\nPluginApiVersions: []string{\"v0.1.0\"} // rebuild against current nomad/plugins/base","handlingStrategy":"validation","validationCode":"// verify overlap between agent-supported and plugin-advertised API versions before deploy\nagentSupported := []string{\"v0.1.0\"} // see nomad/plugins/base\nfor _, av := range pluginInfo.PluginApiVersions {\n\tfor _, s := range agentSupported {\n\t\tif av == s { fmt.Println(\"compatible:\", av); return }\n\t}\n}\nlog.Fatal(\"no plugin API version overlap; rebuild plugin against current base\")","typeGuard":null,"tryCatchPattern":"// Go: treat loader errors as plugin-compatibility failures\ninfos, err := loader.Load()\nif err != nil {\n\tif strings.Contains(err.Error(), \"failed to validate API versions\") {\n\t\tlog.Printf(\"plugin API versions incompatible with agent: %v\", err)\n\t}\n}","preventionTips":["Rebuild all plugins whenever upgrading the Nomad agent to a new plugin API version.","Keep PluginApiVersions in the plugin aligned with versions exported by nomad/plugins/base.","Upgrade Nomad and its first-party plugins together from the same release.","Test fingerprinting in staging (nomad agent -dev with plugin_dir set) before production rollouts."],"tags":["plugin-loader","nomad","api-version","compatibility"],"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"}