hashicorp/nomad · error

failed to create plugin loader: %v

Error message

failed to create plugin loader: %v

What it means

Agent startup error from setupPlugins when loader.NewPluginLoader fails to initialize the plugin loader - typically bad plugin_dir contents, invalid plugin binary/config, or a plugin whose API version is unsupported; it aborts client setup.

Source

Thrown at command/agent/plugins.go:40

	// Build the plugin loader
	config := &loader.PluginLoaderConfig{
		Logger:            a.logger,
		PluginDir:         a.config.PluginDir,
		Configs:           a.config.Plugins,
		InternalPlugins:   internal,
		SupportedVersions: loader.AgentSupportedApiVersions,
	}

	// IMPORTANT: This function will mutate the passed in config to update the
	// plugin configs with any default values from the plugin's config schema.
	//  They need to be propagated so we need to pass a pointer to the
	// agent's config here.
	a.configLock.Lock()
	defer a.configLock.Unlock()

	l, err := loader.NewPluginLoader(config)
	if err != nil {
		return fmt.Errorf("failed to create plugin loader: %v", err)
	}
	a.pluginLoader = l

	// Wrap the loader to get our singleton loader
	a.pluginSingletonLoader = singleton.NewSingletonLoader(a.logger, l)

	for k, plugins := range a.pluginLoader.Catalog() {
		for _, p := range plugins {
			a.logger.Info("detected plugin", "name", p.Name, "type", k, "plugin_version", p.PluginVersion)
		}
	}

	return nil
}

func (a *Agent) internalPluginConfigs() (map[loader.PluginID]*loader.InternalPluginConfig, error) {
	// Get the registered plugins
	catalog := catalog.Catalog()

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check plugin_dir contains valid Nomad plugin binaries built for the server's API version
2. Validate plugin config blocks in the agent configuration
3. Remove or fix broken plugin files and check plugin logs for the underlying loader error

When it happens

Trigger: Thrown at command/agent/plugins.go:40 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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