hashicorp/nomad · error

failed to convert task schema

Error message

failed to convert task schema

What it means

Nomad wraps hclspecutils.Convert failures into 'failed to convert task schema' plus the individual diagnostics when the driver's TaskConfigSchema() HCL spec cannot be converted into a validated cty spec. This happens while building the task runner, before any task config is parsed — the driver itself returned a schema that is internally invalid. Unlike error 65 this is a driver/plugin bug, not a user config error.

Source

Thrown at client/allocrunner/taskrunner/task_runner.go:1028

	tr.UpdateState(structs.TaskStateRunning, structs.NewTaskEvent(structs.TaskStarted))
	return nil
}

// initDriver retrives the DriverPlugin from the plugin loader for this task
func (tr *TaskRunner) initDriver() error {
	driver, err := tr.driverManager.Dispense(tr.Task().Driver)
	if err != nil {
		return err
	}
	tr.driver = driver

	schema, err := tr.driver.TaskConfigSchema()
	if err != nil {
		return err
	}
	spec, diag := hclspecutils.Convert(schema)
	if diag.HasErrors() {
		return multierror.Append(errors.New("failed to convert task schema"), diag.Errs()...)
	}
	tr.taskSchema = spec

	caps, err := tr.driver.Capabilities()
	if err != nil {
		return err
	}
	tr.driverCapabilities = caps

	return nil
}

// handleKill is used to handle the a request to kill a task. It will return
// the handle exit result if one is available and store any error in the task
// runner killErr value.
func (tr *TaskRunner) handleKill(resultCh <-chan *drivers.ExitResult) *drivers.ExitResult {
	// Run the pre killing hooks
	tr.preKill()

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Upgrade or replace the offending driver plugin binary with a build whose TaskConfigSchema is valid
2. Check the appended diag.Errs() in the multierror to find the invalid spec element and fix it in the driver source
3. Verify Nomad client and plugin version compatibility and restart the client to reload the plugin
4. If it's a custom driver, test the schema conversion in the plugin's unit tests with hclspecutils.Convert

Example fix

// before (custom driver)
func (d *Driver) TaskConfigSchema() *hclspec.Spec {
  return hclspec.NewSpec(&hclspec.Spec{ // malformed nested spec
    Attr: append(d.baseAttrs, hclspec.NewAttr("image", "string", true)),
  })
}
// after
func (d *Driver) TaskConfigSchema() *hclspec.Spec {
  return hclspec.NewDefault(hclspec.NewAttr("image", "string", true), nil) // valid spec, tested with Convert
}

// probe the driver before scheduling tasks
schema, err := drv.TaskConfigSchema()
if err != nil { return err }
if spec, diag := hclspecutils.Convert(schema); diag.HasErrors() {
    return fmt.Errorf("driver %s has invalid schema: %v", drvName, diag.Errs())
}

func validTaskSchema(d drivers.DriverPlugin) bool {
    s, err := d.TaskConfigSchema()
    if err != nil { return false }
    _, diag := hclspecutils.Convert(s)
    return !diag.HasErrors()
}

if err := taskRunner.Init(); err != nil {
    var merr *multierror.Error
    if errors.As(err, &merr) && strings.Contains(err.Error(), "failed to convert task schema") {
        // treat as plugin incompatibility: fail the alloc and reload/upgrade the driver plugin
        reloadDriverPlugin(driverName)
    }
    return err
}

When it happens

Trigger: Driver plugin calls TaskConfigSchema() returning an hclspec.Spec block whose conversion via hclspecutils.Convert produces diagnostics: e.g. a spec with an invalid attribute definition, duplicate names, or an unsupported hclspec construct in the installed plugin build.

Common situations: Running a mismatched Nomad client with an older/newer external driver plugin whose schema is invalid; a custom driver plugin with a hand-written hclspec spec containing errors; corrupted or partially-compatible plugin binaries after an upgrade.

Related errors

• error parsing: root should be an object
• failed to parse config:
• <combined HCL diagnostics from str.String()>
• failed to convert HCL schema:
• Invalid or duplicate policy keys: %v

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