hashicorp/nomad · error

invalid plugin loader configuration passed: %v

Error message

invalid plugin loader configuration passed: %v

What it means

NewPluginLoader rejects its PluginLoaderConfig argument when validateConfig fails, wrapping the validation error in this message. The loader requires an agent config, supported versions map, plugin directory, and logger; a nil or incomplete config makes it impossible to construct a PluginLoader.

Source

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

	baseInfo   *base.PluginInfoResponse
	version    *version.Version
	apiVersion string

	configSchema  *hclspec.Spec
	config        map[string]interface{}
	msgpackConfig []byte
}

// NewPluginLoader returns an instance of a plugin loader or an error if the
// plugins could not be loaded
//
// IMPORTANT: This function will mutate the passed in config to update the plugin
// configs with any default values from the plugin's config schema.
// The config should be a pointer to the config in the agent to properly
// update the plugin configs in the agent.
func NewPluginLoader(config *PluginLoaderConfig) (*PluginLoader, error) {
	if err := validateConfig(config); err != nil {
		return nil, fmt.Errorf("invalid plugin loader configuration passed: %v", err)
	}

	// Convert the versions
	supportedVersions := make(map[string][]*version.Version, len(config.SupportedVersions))
	for pType, versions := range config.SupportedVersions {
		converted, err := convertVersions(versions)
		if err != nil {
			return nil, err
		}
		supportedVersions[pType] = converted
	}

	logger := config.Logger.Named("plugin_loader").With("plugin_dir", config.PluginDir)
	l := &PluginLoader{
		logger:            logger,
		supportedVersions: supportedVersions,
		pluginDir:         config.PluginDir,
		plugins:           make(map[PluginID]*pluginInfo),

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped %v detail to see which required field failed validation.
2. Populate all required PluginLoaderConfig fields: AgentConfig, SupportedVersions, PluginDir, Logger.
3. Build the config via a constructor/helper instead of a bare &PluginLoaderConfig{} literal.
4. In tests, use a fixture that sets defaults for every required field.

Example fix

// before
l, err := NewPluginLoader(&loader.PluginLoaderConfig{AgentConfig: cfg})
// after
l, err := NewPluginLoader(&loader.PluginLoaderConfig{
  AgentConfig:       cfg,
  Config:            pluginsConfig,
  PluginDir:         cfg.PluginDir,
  SupportedVersions: supportedVersions,
  Logger:            logger,
})

func validLoaderConfig(c *loader.PluginLoaderConfig) bool {
    return c != nil &&
        c.AgentConfig != nil &&
        c.PluginDir != "" &&
        c.Logger != nil &&
        c.SupportedVersions != nil
}

func isValidLoaderConfig(c interface{}) bool {
    cfg, ok := c.(*loader.PluginLoaderConfig)
    return ok && cfg != nil && cfg.AgentConfig != nil && cfg.Logger != nil
}

l, err := loader.NewPluginLoader(cfg)
if err != nil {
    return fmt.Errorf("loader config invalid: %w", err) // %v detail names the field
}

When it happens

Trigger: Calling NewPluginLoader (directly, in tests like TestPluginLoaderWithOptions, or via setupPlugins/dockerDriverHarness) with a nil *PluginLoaderConfig, nil config.AgentConfig, nil config.SupportedVersions, empty config.PluginDir, or nil config.Logger — whatever validateConfig enforces.

Common situations: Unit tests constructing a PluginLoader with a partially populated PluginLoaderConfig; embedding Nomad plugin loading in another tool and forgetting to set Logger or PluginDir; passing a config struct zero value.

Related errors

• setting config on plugin failed: %v
• setting config for plugin %s failed: %v
• failed to parse config:
• only one of cgroups_v1_override and cgroups_v2_override may
• work_dir must be an absolute path

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