What causes "failed to validate API versions %v for plugin %s (%v): %v" in hashicorp/nomad?

Check the wrapped %v error and compare the plugin's PluginApiVersions with those supported by your Nomad version.

failed to validate API versions %v for plugin %s (%v): %v

Error message

failed to validate API versions %v for plugin %s (%v): %v

What it means

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.

Source

Thrown at helper/pluginutils/loader/init.go:390

	// Retrieve base plugin information
	i, err := bplugin.PluginInfo()
	if err != nil {
		return nil, fmt.Errorf("failed to get plugin info for plugin %q: %v", info.exePath, err)
	}
	info.baseInfo = i

	// Parse and set the plugin version
	v, err := version.NewVersion(i.PluginVersion)
	if err != nil {
		return nil, fmt.Errorf("failed to parse plugin %q (%v) version %q: %v",
			i.Name, info.exePath, i.PluginVersion, err)
	}
	info.version = v

	// Detect the plugin API version to use
	av, err := l.selectApiVersion(i)
	if err != nil {
		return nil, fmt.Errorf("failed to validate API versions %v for plugin %s (%v): %v", i.PluginApiVersions, i.Name, info.exePath, err)
	}
	if av == "" {
		l.logger.Warn("skipping plugin because supported API versions for plugin and Nomad do not overlap", "plugin", i.Name, "path", info.exePath)
		return nil, nil
	}
	info.apiVersion = av

	// Retrieve the schema
	schema, err := bplugin.ConfigSchema()
	if err != nil {
		return nil, fmt.Errorf("failed to get plugin config schema for plugin %q: %v", info.exePath, err)
	}
	info.configSchema = schema

	return info, nil
}

// mergePlugins merges internal and external plugins, preferring the highest

View on GitHub (pinned to 482b49bf1a)

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.

Example fix

// before (plugin advertising unsupported API version)
PluginApiVersions: []string{"v9.9.9"}
// after
PluginApiVersions: []string{"v0.1.0"} // rebuild against current nomad/plugins/base

Defensive patterns

Strategy: validation

Validate before calling

// verify overlap between agent-supported and plugin-advertised API versions before deploy
agentSupported := []string{"v0.1.0"} // see nomad/plugins/base
for _, av := range pluginInfo.PluginApiVersions {
	for _, s := range agentSupported {
		if av == s { fmt.Println("compatible:", av); return }
	}
}
log.Fatal("no plugin API version overlap; rebuild plugin against current base")

Try / catch

// Go: treat loader errors as plugin-compatibility failures
infos, err := loader.Load()
if err != nil {
	if strings.Contains(err.Error(), "failed to validate API versions") {
		log.Printf("plugin API versions incompatible with agent: %v", err)
	}
}

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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).

Related errors

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/ee473374f067eaa0. Report an issue: GitHub.