failed to reattach to plugin because supported API versions

Error message

failed to reattach to plugin because supported API versions for the plugin and Nomad do not overlap

What it means

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.

Source

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

	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 {
	case base.PluginTypeDevice:
		pmap[base.PluginTypeDevice] = &device.PluginDevice{}
	case base.PluginTypeDriver:

View on GitHub (pinned to 482b49bf1a)

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)

Example fix

// before: nomad 0.11 reattaching to old docker logging plugin with only v0 API
// after: upgrade the plugin binary in plugin_dir to one supporting v1, then restart agent

Defensive patterns

Strategy: retry

Validate before calling

// before reattach, check plugin API version overlap
supported := map[string]bool{"v1": true}
overlap := false
for _, v := range info.PluginApiVersions { if supported[v] { overlap = true } }
if !overlap { return fmt.Errorf("plugin %s incompatible with this Nomad", info.Name) }

Try / catch

inst, err := loader.Reattach(...)
if err != nil {
    if strings.Contains(err.Error(), "do not overlap") {
        // force a fresh launch instead of reattach
        os.Remove(reattachConfigPath)
        inst, err = loader.Dispense(...)
    }
}

Prevention

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

When it happens

Trigger: loader.Reattach (or Dispense) to an existing plugin whose PluginApiVersions share no entry with Nomad's supported API versions.

Common situations: Nomad upgraded or downgraded past what the installed plugin supports; reattaching to a stale plugin process left over from a previous Nomad version.

Related errors

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