hashicorp/nomad · error

parsing plugin configurations failed: %v

Error message

parsing plugin configurations failed: %v

What it means

After merging internal and external plugins, validatePluginConfigs decodes and canonicalizes each plugin's HCL configuration against the plugin's own config spec. Errors from that parsing/validation are wrapped with this message and returned by NewPluginLoader.

Source

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

	// Scan for eligibile binaries
	plugins, err := l.scan()
	if err != nil {
		return nil, fmt.Errorf("failed to scan plugin directory %q: %v", l.pluginDir, err)
	}

	// Fingerprint the passed plugins
	external, err := l.fingerprintPlugins(plugins, configMap)
	if err != nil {
		return nil, fmt.Errorf("failed to fingerprint plugins: %v", err)
	}

	// Merge external and internal plugins
	l.plugins = l.mergePlugins(internal, external)

	// Validate that the configs are valid for the plugins
	canonicalizedConfigs, err := l.validatePluginConfigs()
	if err != nil {
		return nil, fmt.Errorf("parsing plugin configurations failed: %v", err)
	}

	for i := range configMap {
		if updated, ok := canonicalizedConfigs[i]; ok {
			configMap[i].Config = updated.Config
		}
	}

	return configMap, nil
}

// initInternal initializes internal plugins.
func (l *PluginLoader) initInternal(plugins map[PluginID]*InternalPluginConfig, configs map[string]*config.PluginConfig) (map[PluginID]*pluginInfo, error) {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	var mErr multierror.Error
	fingerprinted := make(map[PluginID]*pluginInfo, len(plugins))

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped inner error to identify the offending plugin and config key.
2. Fix the option names/types in the plugin's config to match the plugin's documented schema.
3. Run the plugin standalone with `plugin -config <file>` (where supported) to validate config before loading.
4. If you upgraded a plugin, migrate its config to the new schema.

Example fix

// before
// plugin config hcl
config {
  "endpoint" = "unix:///var/run/docker.sock"
  "retries" = "3"   # string where int expected
}

// after
config {
  endpoint = "unix:///var/run/docker.sock"
  retries  = 3
}

for _, c := range cfg.Configs {
    if err := validateAgainstPluginSchema(c.Name, c.Config); err != nil {
        return fmt.Errorf("plugin %q config invalid: %w", c.Name, err)
    }
}

loader, err := NewPluginLoader(cfg)
if err != nil {
    if strings.Contains(err.Error(), "parsing plugin configurations failed") {
        return fmt.Errorf("fix plugin HCL config per error detail: %w", err)
    }
    return err
}

When it happens

Trigger: A plugin's config map contains keys the plugin doesn't recognize, values of the wrong type (string where an int is expected), or malformed HCL that cannot be decoded into the plugin's config struct.

Common situations: Hand-written HCL config with typos in option names; config copied from an older plugin version whose schema changed; passing environment-specific values (e.g. a string port) that the plugin expects as numbers; nested blocks supplied where only flat options are supported.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• plugin config passed without binary name
• nil config passed for internal plugin %s
• nil factory passed for internal plugin %s
• ErrPluginNotExecutable
• dynamic workload users disabled

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