What causes "plugin provided invalid versions: %v" in hashicorp/nomad?

Use valid semver strings with an optional v prefix, e.g. "v1.0.0" or "1.0.0"

plugin provided invalid versions: %v

Error message

plugin provided invalid versions: %v

What it means

The plugin's declared PluginApiVersions strings are parsed with go-version via convertVersions. Any string that is not a valid version (e.g. "", "one", "1.x") aborts negotiation with this wrapped error.

Source

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

	}

	return fingerprinted, nil
}

// selectApiVersion takes in PluginInfo and returns the highest compatable
// version or an error if the plugins response is malformed. If there is no
// overlap, an empty string is returned.
func (l *PluginLoader) selectApiVersion(i *base.PluginInfoResponse) (string, error) {
	if i == nil {
		return "", fmt.Errorf("nil plugin info given")
	}
	if len(i.PluginApiVersions) == 0 {
		return "", fmt.Errorf("plugin provided no compatible API versions")
	}

	pluginVersions, err := convertVersions(i.PluginApiVersions)
	if err != nil {
		return "", fmt.Errorf("plugin provided invalid versions: %v", err)
	}

	// Lookup the supported versions. These will be sorted highest to lowest
	supportedVersions, ok := l.supportedVersions[i.Type]
	if !ok {
		return "", fmt.Errorf("unsupported plugin type %q", i.Type)
	}

	for _, sv := range supportedVersions {
		for _, pv := range pluginVersions {
			if sv.Equal(pv) {
				return pv.Original(), nil
			}
		}
	}

	return "", nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

Use valid semver strings with an optional v prefix, e.g. "v1.0.0" or "1.0.0"
Check the wrapped %v for which entry failed to parse and correct it in the plugin
Add a quick local check version.NewVersion(v) in plugin tests to catch bad version constants

Example fix

// before
PluginApiVersions: []string{"csi-v1"}
// after
PluginApiVersions: []string{"v1.0.0"}

Defensive patterns

Strategy: validation

Validate before calling

for _, v := range info.PluginApiVersions {
    if _, err := version.NewVersion(v); err != nil {
        return fmt.Errorf("bad API version %q: %w", v, err)
    }
}

Try / catch

if err := loader.Init(...); err != nil {
    if strings.Contains(err.Error(), "plugin provided invalid versions") {
        // parse each PluginApiVersions entry with version.NewVersion to find the offender
    }
}

Prevention

Use plain semver strings ("v1", "1.0.0") with no prose or protocol names
Validate the version list with go-version in the plugin's tests
Keep API version strings as shared constants, not literals scattered in code

When it happens

Trigger: selectApiVersion calls convertVersions(i.PluginApiVersions) and version.NewVersion fails on one of the entries.

Common situations: Hand-written version strings like "v1-alpha" or "1" with stray characters; a plugin declaring "latest" or a protocol name instead of a semver.

Related errors

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