hashicorp/nomad · error

dispensed plugin %s doesn't meet base plugin interface

Error message

dispensed plugin %s doesn't meet base plugin interface

What it means

After successfully dispensing the plugin, validatePluginConfig asserts the dispensed instance implements the base.BasePlugin interface (instance.Plugin().(base.BasePlugin)). If the type assertion fails, the plugin can be launched but does not expose the base plugin surface (SetConfig/SetDevice etc.) required for configuration, so loading aborts with this message including the plugin ID.

Source

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

	// Marshal the value
	cdata, err := msgpack.Marshal(val, val.Type())
	if err != nil {
		return nil, fmt.Errorf("failed to msgpack encode config: %v", err)
	}

	// Store the marshalled config
	info.msgpackConfig = cdata

	// Dispense the plugin and set its config and ensure it is error free
	instance, err := l.Dispense(id.Name, id.PluginType, nil, l.logger)
	if err != nil {
		return nil, fmt.Errorf("failed to dispense plugin: %v", err)
	}
	defer instance.Kill()

	b, ok := instance.Plugin().(base.BasePlugin)
	if !ok {
		return nil, fmt.Errorf("dispensed plugin %s doesn't meet base plugin interface", id)
	}

	c := &base.Config{
		PluginConfig: cdata,
		AgentConfig:  nil,
		ApiVersion:   info.apiVersion,
	}

	if err := b.SetConfig(c); err != nil {
		return nil, fmt.Errorf("setting config on plugin failed: %v", err)
	}

	parsedConfig, err := hclutils.CtyValueToMapInterface(val)
	if err != nil {
		return nil, fmt.Errorf("failed to convert parsed config to map: %v", err)
	}

	return parsedConfig, nil

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Rebuild/reinstall the plugin against the current host SDK so its Plugin() returns a type implementing base.BasePlugin (SetConfig, PluginApiVersion, etc.).
2. Match host and plugin versions — check the plugin's supported API versions vs info.apiVersion negotiated at fingerprint time.
3. Verify the correct plugin binary is registered for this name/type (no stale binary shadowing in plugin_dir).
4. If authoring the plugin, embed/implement base.BasePluginBase or ensure your plugin struct satisfies the full interface and return it from Plugin().

Example fix

// before (plugin-side: custom type without base interface)
func (p *MyPlugin) Plugin() interface{} { return &myRawPlugin{} }
// after (embed the base plugin so the assertion succeeds)
func (p *MyPlugin) Plugin() interface{} {
    return &myPlugin{BasePlugin: *base.NewBasePlugin(...)}
}

// Check the plugin's advertised API version against the host's supported versions before loading
if !slices.Contains(supportedAPIVersions, pluginInfo.APIVersion.Provider) {
    return fmt.Errorf("plugin %s uses unsupported API version", name)
}

func asBasePlugin(p interface{}) (base.BasePlugin, bool) {
    bp, ok := p.(base.BasePlugin)
    return bp, ok
}

if err := loader.Load(cfg); err != nil {
    if strings.Contains(err.Error(), "doesn't meet base plugin interface") {
        return fmt.Errorf("plugin %s is built against an incompatible SDK; rebuild it with the current base plugin package", name)
    }
    return err
}

When it happens

Trigger: validatePluginConfig performs `b, ok := instance.Plugin().(base.BasePlugin)` and ok is false — the registered plugin's Plugin() returns a type that doesn't implement base.BasePlugin (e.g. an older plugin or a plugin built against an incompatible base package).

Common situations: Plugin compiled against an old vendored base plugin package that predates BasePlugin interface methods; host upgraded to a new plugin API while the plugin binary is stale; a custom plugin type registered that only implements go-plugin.Plugin, not BasePlugin.

Related errors

• plugin %s doesn't implement base plugin interface
• CSI Plugin loaded incorrectly
• plugin loaded does not implement the driver interface
• plugin loaded does not implement the driver interface
• writer ui: unsupported Ui type: %T

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