hashicorp/nomad · error

failed to get plugin config schema for plugin %q: %v

Error message

failed to get plugin config schema for plugin %q: %v

What it means

During plugin fingerprinting, the loader calls bplugin.ConfigSchema() on the launched external plugin to discover its configuration schema. If the plugin's gRPC ConfigSchema call fails (transport error, plugin crash, method not implemented for its API version, etc.), fingerprintPlugin wraps the underlying error with this message using the plugin's executable path. The plugin instance is discarded and the plugin fails to load.

Source

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

			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
// version.
func (l *PluginLoader) mergePlugins(internal, external map[PluginID]*pluginInfo) map[PluginID]*pluginInfo {
	finalized := make(map[PluginID]*pluginInfo, len(internal))

	// Load the internal plugins
	for k, v := range internal {
		finalized[k] = v
	}

	for k, extPlugin := range external {
		internal, ok := finalized[k]

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped %v cause in the error message and fix the plugin's ConfigSchema implementation to return a valid schema or nil without error.
2. Verify the plugin binary is compatible with the host's supported plugin API versions (rebuild the plugin against the same sdk/base packages).
3. Run the plugin binary standalone to confirm it starts and serves gRPC without crashing (check permissions, missing shared libs, architecture).
4. Update the host (e.g. Nomad) or the plugin to matching versions so the API version negotiated (info.apiVersion) supports ConfigSchema.

Example fix

// before (plugin-side, API v01 where ConfigSchema unsupported or errors)
func (p *MyPlugin) ConfigSchema() (*hclspec.Spec, error) {
    return nil, fmt.Errorf("not implemented")
}
// after
func (p *MyPlugin) ConfigSchema() (*hclspec.Spec, error) {
    return hclspec.NewObject(map[string]*hclspec.Spec{
        "endpoint": hclspec.NewAttr("endpoint", "string", true),
    }), nil
}

// Before loading, sanity-check the plugin binary
cmd := exec.Command(pluginPath, "--help")
if err := cmd.Run(); err != nil {
    return fmt.Errorf("plugin %s cannot start: %w", pluginPath, err)
}

func hasConfigSchema(info *loader.PluginInfo) bool {
    return info != nil && info.ConfigSchema != nil
}

info, err := fingerprintPlugin(...)
if err != nil {
    if strings.Contains(err.Error(), "failed to get plugin config schema") {
        log.Printf("plugin %s does not expose a config schema; check binary/API version", pluginPath)
        return nil // skip or fail loudly, with the inner cause logged
    }
    return err
}

When it happens

Trigger: Calling loader.Init/getPluginLoader when an external plugin binary registers successfully but its BasePlugin.ConfigSchema() gRPC invocation returns an error, panics, or the plugin process dies mid-call during fingerprintPlugin.

Common situations: Plugin binary built against an incompatible go-plugin/base API version so ConfigSchema isn't supported; plugin crashes on startup before serving the RPC; mismatched Nomad/plugin dependency versions; binary lacks execute permissions or segfaults under load.

Related errors

• PluginInfo info failed for internal plugin %s: %v
• failed to retrieve config schema for internal plugin %s: %v
• failed to get plugin info for plugin %q: %v
• failed to parse plugin %q (%v) version %q: %v
• missing accessor ID

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