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

Read the wrapped error to see why validation failed

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

Error message

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

What it means

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>'.

Source

Thrown at helper/pluginutils/loader/loader.go:273

		instance: raw,
	}

	if apiVersion != "" {
		instance.apiVersion = apiVersion
	} else {
		// We do not know the API version since we are reattaching, so discover
		// it
		bplugin := raw.(base.BasePlugin)

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

		apiVersion, err := l.selectApiVersion(i)
		if err != nil {
			return nil, fmt.Errorf("failed to validate API versions %v for plugin %s: %v", i.PluginApiVersions, i.Name, err)
		}
		if apiVersion == "" {
			return nil, fmt.Errorf("failed to reattach to plugin because supported API versions for the plugin and Nomad do not overlap")
		}

		instance.apiVersion = apiVersion
	}

	return instance, nil
}

// getPluginMap returns a plugin map based on the type of plugin being launched.
func getPluginMap(pluginType string, logger log.Logger) map[string]plugin.Plugin {
	pmap := map[string]plugin.Plugin{
		base.PluginTypeBase: &base.PluginBase{},
	}

	switch pluginType {

View on GitHub (pinned to 482b49bf1a)

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

Example fix

// before: plugin reports PluginApiVersions: []string{} 
// after: rebuild plugin so it registers e.g. []string{"v1"}

Defensive patterns

Strategy: validation

Validate before calling

// validate plugin info before relying on dispense
// (server side ensure PluginApiVersions non-empty and known)
if len(info.PluginApiVersions) == 0 { return fmt.Errorf("plugin declares no API versions") }

Try / catch

inst, err := loader.Dispense(name, ptype, cfg, logger)
if err != nil {
    if strings.Contains(err.Error(), "failed to validate API versions") {
        logger.Error("plugin API version negotiation failed", "err", err)
    }
    return err
}

Prevention

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

When it happens

Trigger: loader.Dispense/Reattach where l.selectApiVersion(i) errors, e.g. the plugin declares malformed or empty PluginApiVersions.

Common situations: A plugin built for a different Nomad version declaring API versions Nomad cannot validate, or a plugin emitting an empty/duplicated API version set.

Related errors

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