hashicorp/nomad · critical

failed to initialize plugin loader: %v

Error message

failed to initialize plugin loader: %v

What it means

NewPluginLoader calls l.init(config) which scans the plugin directory, launches/factories each plugin to fetch its schema and API version, and applies schema defaults. Any failure in that bootstrap is wrapped as "failed to initialize plugin loader". Unlike the config-validation error (1852), this one happens after validation, during actual plugin discovery and handshake.

Source

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

	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),
	}

	updatedConfig, err := l.init(config)
	if err != nil {
		return nil, fmt.Errorf("failed to initialize plugin loader: %v", err)
	}

	// DANGER! Secondary effect of init is that it updates the plugin configs
	// in the loader's plugins map with any default values from the plugin schemas.
	//  We need to propagate those updated configs back to the agent config
	// since the agent will use those to report the plugings configs in the API.
	for i, c := range config.Configs {
		if updated, ok := updatedConfig[c.Name]; ok {
			config.Configs[i] = updated
		}
	}

	return l, nil
}

// Dispense returns a plugin instance, loading it either internally or by
// launching an external plugin.
func (l *PluginLoader) Dispense(name, pluginType string, config *base.AgentConfig, logger log.Logger) (PluginInstance, error) {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped %v detail to identify which plugin or step failed.
2. Verify plugin_dir exists, is readable/executable, and contains the intended plugin binaries.
3. Check each external plugin's supported API version against the Nomad SupportedVersions list.
4. Run the plugin binary manually to see if it starts and handshakes correctly.
5. Update or remove the offending plugin binary from plugin_dir.

Example fix

// before
$ ls $PLUGIN_DIR
nomad-docker  # no exec bit
// after
$ chmod +x $PLUGIN_DIR/nomad-docker
$ nomad agent -config agent.hcl

info, err := os.Stat(pluginDir)
if err != nil || !info.IsDir() {
    return fmt.Errorf("plugin dir missing: %s", pluginDir)
}
// also: check each entry is executable
ents, _ := os.ReadDir(pluginDir)
for _, e := range ents {
    if fi, _ := e.Info(); fi != nil && fi.Mode()&0111 == 0 {
        log.Warn("plugin not executable", "file", e.Name())
    }
}

l, err := loader.NewPluginLoader(cfg)
if err != nil && strings.Contains(err.Error(), "failed to initialize plugin loader") {
    log.Error("plugin discovery failed; check plugin_dir and binaries", "cause", err)
    return err
}

When it happens

Trigger: Calling NewPluginLoader when l.init fails: plugin dir unreadable, a plugin binary fails to launch/handshake, an external plugin's API version is unsupported, or schema/default application errors for a plugin config.

Common situations: Misconfigured plugin_dir path or wrong permissions; external plugin binaries missing, non-executable, or built against an incompatible API version; a plugin crashing during startup; duplicate plugin names/types on disk.

Related errors

• unknown plugin with name %q and type %q
• cni not initialized: %w
• init of plugin %s failed: %w
• PluginInfo info failed for internal plugin %s: %v
• failed to parse version %q for internal plugin %s: %v

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