failed to retrieve config schema for internal plugin %s: %v

Error message

failed to retrieve config schema for internal plugin %s: %v

What it means

After selecting the API version, initInternal asks the plugin for its configuration schema via base.ConfigSchema(). If the plugin returns an error, this message is appended to the multierror and the plugin is skipped, since the loader cannot validate the plugin's config without a schema.

Source

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

		}
		info.version = v

		// Detect the plugin API version to use
		av, err := l.selectApiVersion(i)
		if err != nil {
			_ = multierror.Append(&mErr, fmt.Errorf("failed to validate API versions %v for internal plugin %s: %v", i.PluginApiVersions, k, err))
			continue
		}
		if av == "" {
			l.logger.Warn("skipping plugin because supported API versions for plugin and Nomad do not overlap", "plugin", k)
			continue
		}
		info.apiVersion = av

		// Get the config schema
		schema, err := base.ConfigSchema()
		if err != nil {
			_ = multierror.Append(&mErr, fmt.Errorf("failed to retrieve config schema for internal plugin %s: %v", k, err))
			continue
		}
		info.configSchema = schema

		// Store the fingerprinted config
		fingerprinted[k] = info
	}

	if err := mErr.ErrorOrNil(); err != nil {
		return nil, err
	}

	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.

View on GitHub (pinned to 482b49bf1a)

Solutions

Implement ConfigSchema in the plugin's base so it returns a valid hclspec.Schema for the negotiated API version
Check the wrapped %v error for the root cause returned by the plugin
Downgrade/upgrade so a supported API version is negotiated for which the plugin implements ConfigSchema

Defensive patterns

Strategy: validation

Validate before calling

schema, err := p.ConfigSchema()
if err != nil || schema == nil {
    return fmt.Errorf("plugin must return a non-nil config schema")
}

Try / catch

if err := loader.Init(...); err != nil {
    if strings.Contains(err.Error(), "failed to retrieve config schema") {
        // plugin's ConfigSchema failed; check the inner error for the cause
    }
}

Prevention

Implement ConfigSchema for every supported API version
Return a static hclspec schema rather than one derived from mutable state
Cover ConfigSchema in the plugin's unit tests

When it happens

Trigger: initInternal calls base.ConfigSchema() on the fingerprinted internal plugin and it errors — typically a plugin whose schema method is unimplemented for the negotiated API version or returns an error derived from internal state.

Common situations: Custom internal plugin implements ConfigSchema incorrectly or not at all; negotiated API version lacks a schema implementation; plugin misconfigured such that schema generation depends on failing state.

Related errors

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