hashicorp/nomad · error

setting config on plugin failed: %v

Error message

setting config on plugin failed: %v

What it means

This error wraps a failure from BasePlugin.SetConfig during plugin config validation in the Nomad plugin loader. SetConfig pushes the user-supplied HCL config (parsed to a Cty value) into the plugin process via the base plugin interface; the plugin itself may reject it (schema mismatch, required fields missing, invalid values) or the RPC may fail. It means the loader could not successfully apply the given configuration to the plugin before running it.

Source

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

	instance, err := l.Dispense(id.Name, id.PluginType, nil, l.logger)
	if err != nil {
		return nil, fmt.Errorf("failed to dispense plugin: %v", err)
	}
	defer instance.Kill()

	b, ok := instance.Plugin().(base.BasePlugin)
	if !ok {
		return nil, fmt.Errorf("dispensed plugin %s doesn't meet base plugin interface", id)
	}

	c := &base.Config{
		PluginConfig: cdata,
		AgentConfig:  nil,
		ApiVersion:   info.apiVersion,
	}

	if err := b.SetConfig(c); err != nil {
		return nil, fmt.Errorf("setting config on plugin failed: %v", err)
	}

	parsedConfig, err := hclutils.CtyValueToMapInterface(val)
	if err != nil {
		return nil, fmt.Errorf("failed to convert parsed config to map: %v", err)
	}

	return parsedConfig, nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped %v detail to see the plugin's own SetConfig error message and fix the offending config field.
2. Validate the plugin stanza against the plugin's documented config schema (field names and types).
3. Run `nomad agent config validate` (or the plugin's own validation command) before restarting the agent.
4. Check the plugin binary version matches the Nomad API version it was built against; upgrade or downgrade the plugin.
5. Verify the plugin process starts and its logs for panics during config handling.

Example fix

// before (agent config)
plugin "docker" {
  volum = "/mnt/data"   # typo, rejected by plugin schema
}
// after
plugin "docker" {
  volumes_dir = "/mnt/data"
}

// Validate the agent config (plugin stanzas) before starting:
// use the loader's validate path or the plugin's own schema
if err := hclutils.ParseHclInterface(rawCfg, pluginConfigSchema, &out); err != nil {
    return fmt.Errorf("plugin config does not match schema: %w", err)
}

if _, err := loader.NewPluginLoader(cfg); err != nil {
    if strings.Contains(err.Error(), "setting config on plugin failed") {
        // surface wrapped cause: err.Error() includes plugin's SetConfig error
        return fmt.Errorf("fix plugin config: %w", err)
    }
    return err
}

When it happens

Trigger: Calling validatePluginConfig (via validatePluginConfigs during agent startup or `nomad agent config validate`) when the constructed base.Config triggers b.SetConfig to return an error: the plugin's SetConfig RPC returns an error, the plugin process dies mid-call, or the config violates the plugin's Cty schema.

Common situations: Typo'd or unsupported keys in a plugin stanza in the Nomad agent config; required plugin config fields left empty; config type mismatches (string vs number); external plugin binary crashing during its SetConfig handler; plugin API-version mismatch causing decode errors.

Related errors

• invalid plugin loader configuration passed: %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/83fa1e3ad9cb9b4c. Report an issue: GitHub.