hashicorp/nomad · error

failed to get config schema: %v

Error message

failed to get config schema: %v

What it means

getSpec obtains the device plugin's configuration schema via dev.ConfigSchema() so the launcher can parse device config. This error wraps any failure from that call, meaning the plugin could not supply a valid HCL spec schema.

Source

Thrown at plugins/shared/cmd/launcher/command/device.go:173

	// Request the plugin
	raw, err := rpcClient.Dispense(base.PluginTypeDevice)
	if err != nil {
		client.Kill()
		return nil, nil, err
	}

	// We should have a KV store now! This feels like a normal interface
	// implementation but is in fact over an RPC connection.
	dev := raw.(device.DevicePlugin)
	return dev, func() { client.Kill() }, nil
}

func (c *Device) getSpec() (hcldec.Spec, error) {
	// Get the schema so we can parse the config
	spec, err := c.dev.ConfigSchema()
	if err != nil {
		return nil, fmt.Errorf("failed to get config schema: %v", err)
	}

	// Convert the schema
	schema, diag := hclspecutils.Convert(spec)
	if diag.HasErrors() {
		errStr := "failed to convert HCL schema: "
		for _, err := range diag.Errs() {
			errStr = fmt.Sprintf("%s\n* %s", errStr, err.Error())
		}
		return nil, errors.New(errStr)
	}

	return schema, nil
}

func (c *Device) setConfig(spec hcldec.Spec, apiVersion string, config []byte, nmdCfg *base.AgentConfig) error {
	// Parse the config into hcl
	configVal, err := hclConfigToAny(config)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped %v error and check the device plugin's logs/stderr for the root cause.
2. Verify the device plugin binary runs standalone and is compatible with the launcher's plugin protocol.
3. Restart the device plugin process / re-provision plugin binaries.
4. If the plugin is custom, fix ConfigSchema() to return a valid hclspec.Spec without error.

Example fix

// before
func (d *MyDevice) ConfigSchema() (*hclspec.Spec, error) { return nil, fmt.Errorf("not ready") }
// after
func (d *MyDevice) ConfigSchema() (*hclspec.Spec, error) {
	return hclspec.NewBlockList("config", configSpec), nil
}

// Health-check the device plugin before requesting its schema
if err := devicePluginPing(dev); err != nil {
	return fmt.Errorf("device plugin not healthy: %w", err)
}

spec, err := c.getSpec()
if err != nil && strings.Contains(err.Error(), "failed to get config schema") {
	// restart/reconnect the plugin, then retry once
}

When it happens

Trigger: Calling Device.Run -> getSpec when the device plugin's ConfigSchema() returns an error, e.g. the plugin process is unhealthy, misconfigured, or its schema generation failed.

Common situations: Device plugin binary failing at startup or crashing; plugin returning a nil/invalid schema due to a bug; gRPC failure between the launcher and the device plugin; incompatible plugin/launcher versions.

Related errors

• plugin not found
• failed to decode HCL file %s: %w
• failed to hcl parse the config: %v
• root should be an object
• failed to decode object: %v

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