{"record":{"id":"753c623db62fb552","repo":"hashicorp/nomad","slug":"failed-to-convert-task-schema","errorCode":null,"errorMessage":"failed to convert task schema","messagePattern":"failed to convert task schema","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/allocrunner/taskrunner/task_runner.go","lineNumber":1028,"sourceCode":"\ttr.UpdateState(structs.TaskStateRunning, structs.NewTaskEvent(structs.TaskStarted))\n\treturn nil\n}\n\n// initDriver retrives the DriverPlugin from the plugin loader for this task\nfunc (tr *TaskRunner) initDriver() error {\n\tdriver, err := tr.driverManager.Dispense(tr.Task().Driver)\n\tif err != nil {\n\t\treturn err\n\t}\n\ttr.driver = driver\n\n\tschema, err := tr.driver.TaskConfigSchema()\n\tif err != nil {\n\t\treturn err\n\t}\n\tspec, diag := hclspecutils.Convert(schema)\n\tif diag.HasErrors() {\n\t\treturn multierror.Append(errors.New(\"failed to convert task schema\"), diag.Errs()...)\n\t}\n\ttr.taskSchema = spec\n\n\tcaps, err := tr.driver.Capabilities()\n\tif err != nil {\n\t\treturn err\n\t}\n\ttr.driverCapabilities = caps\n\n\treturn nil\n}\n\n// handleKill is used to handle the a request to kill a task. It will return\n// the handle exit result if one is available and store any error in the task\n// runner killErr value.\nfunc (tr *TaskRunner) handleKill(resultCh <-chan *drivers.ExitResult) *drivers.ExitResult {\n\t// Run the pre killing hooks\n\ttr.preKill()","sourceCodeStart":1010,"sourceCodeEnd":1046,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/allocrunner/taskrunner/task_runner.go#L1010-L1046","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade or replace the offending driver plugin binary with a build whose TaskConfigSchema is valid","Check the appended diag.Errs() in the multierror to find the invalid spec element and fix it in the driver source","Verify Nomad client and plugin version compatibility and restart the client to reload the plugin","If it's a custom driver, test the schema conversion in the plugin's unit tests with hclspecutils.Convert"],"exampleFix":"// before (custom driver)\nfunc (d *Driver) TaskConfigSchema() *hclspec.Spec {\n  return hclspec.NewSpec(&hclspec.Spec{ // malformed nested spec\n    Attr: append(d.baseAttrs, hclspec.NewAttr(\"image\", \"string\", true)),\n  })\n}\n// after\nfunc (d *Driver) TaskConfigSchema() *hclspec.Spec {\n  return hclspec.NewDefault(hclspec.NewAttr(\"image\", \"string\", true), nil) // valid spec, tested with Convert\n}","handlingStrategy":"type-guard","validationCode":"// probe the driver before scheduling tasks\nschema, err := drv.TaskConfigSchema()\nif err != nil { return err }\nif spec, diag := hclspecutils.Convert(schema); diag.HasErrors() {\n    return fmt.Errorf(\"driver %s has invalid schema: %v\", drvName, diag.Errs())\n}","typeGuard":"func validTaskSchema(d drivers.DriverPlugin) bool {\n    s, err := d.TaskConfigSchema()\n    if err != nil { return false }\n    _, diag := hclspecutils.Convert(s)\n    return !diag.HasErrors()\n}","tryCatchPattern":"if err := taskRunner.Init(); err != nil {\n    var merr *multierror.Error\n    if errors.As(err, &merr) && strings.Contains(err.Error(), \"failed to convert task schema\") {\n        // treat as plugin incompatibility: fail the alloc and reload/upgrade the driver plugin\n        reloadDriverPlugin(driverName)\n    }\n    return err\n}","preventionTips":["Pin compatible Nomad client and driver plugin versions","Add unit tests in custom drivers that convert TaskConfigSchema via hclspecutils.Convert","Smoke-test plugins with 'nomad plugin status' and a canary task after upgrades","Watch plugin logs at client startup for schema errors"],"tags":["nomad","hcl","driver-plugin","schema"],"backgroundTag":"task-schema-conversion-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}