hashicorp/nomad · error

failed to parse config:

Error message

failed to parse config: 

What it means

Nomad's task runner wraps all HCL parsing diagnostics from hclutils.ParseHclInterface into a single multierror prefixed 'failed to parse config: ' when converting a task's raw config into the driver's typed configuration. The trailing colon in the message means the individual HCL diagnostics are appended as sub-errors of the multierror. It is thrown by the task runner's preStart hook path and emitted as a TaskFailedValidation event before the task is started.

Source

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

	// Handle per-key errors
	if len(errs) > 0 {
		keys := make([]string, 0, len(errs))
		for k, err := range errs {
			keys = append(keys, k)

			if tr.logger.IsTrace() {
				// Verbosely log every diagnostic for debugging
				tr.logger.Trace("error building environment variables", "key", k, "error", err)
			}
		}

		tr.logger.Warn("some environment variables not available for rendering", "keys", strings.Join(keys, ", "))
	}

	val, diag, diagErrs := hclutils.ParseHclInterface(tr.task.Config, tr.taskSchema, vars)
	if diag.HasErrors() {
		parseErr := multierror.Append(errors.New("failed to parse config: "), diagErrs...)
		tr.EmitEvent(structs.NewTaskEvent(structs.TaskFailedValidation).SetValidationError(parseErr))
		return parseErr
	}

	if err := taskConfig.EncodeDriverConfig(val); err != nil {
		encodeErr := fmt.Errorf("failed to encode driver config: %v", err)
		tr.EmitEvent(structs.NewTaskEvent(structs.TaskFailedValidation).SetValidationError(encodeErr))
		return encodeErr
	}

	// If there's already a task handle (eg from a Restore) there's nothing
	// to do except update state.
	if tr.getDriverHandle() != nil {
		// Ensure running state is persisted but do *not* append a new
		// task event as restoring is a client event and not relevant
		// to a task's lifecycle.
		if err := tr.updateStateImpl(structs.TaskStateRunning); err != nil {
			//TODO return error and destroy task to avoid an orphaned task?

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the appended hcl.Diagnostics sub-errors in the multierror for the exact offending attribute and fix the task config block
2. Validate the task config against the driver's TaskConfigSchema (nomad job validate or nomad plan catches most of these client-side)
3. Check driver version compatibility: schema fields may have been renamed or removed between driver releases
4. If variables fail to render, fix interpolation syntax or provide the missing variables before the task starts

Example fix

// before
config {
  image = "nginx"
  port = "8080h"  // invalid: schema expects number
}
// after
config {
  image = "nginx"
  ports = ["http"]
  port  = 8080
}

// pre-validate the raw task config HCL before submit
// nomad job validate job.nomad.hcl
if diag := hclutils.ParseHclInterface(rawCfg, driverSchema, vars); diag.HasErrors() {
    for _, d := range diag.Errs() {
        log.Printf("config problem: %s", d)
    }
    return fmt.Errorf("task config invalid: %s", errorSummary(diag))
}

err := tr.runPreStart()
if err != nil {
    var merr *multierror.Error
    if errors.As(err, &merr) {
        for _, e := range merr.Errors {
            log.Printf("config error: %v", e)
        }
    }
    return err
}

When it happens

Trigger: tr.task.Config fails hclutils.ParseHclInterface against the driver's taskSchema (hclspecutils-converted spec), e.g. unknown keys, wrong types, missing required fields, or invalid interpolation of template variables in the task's config block.

Common situations: Typo'd or unsupported keys in a task's config block after a driver/plugin version change; passing a string where the driver schema expects a number/bool; referencing env vars or node attributes that don't resolve at client-side rendering time; copying config from one driver to another with an incompatible schema.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to convert task schema
• only one of cgroups_v1_override and cgroups_v2_override may
• work_dir must be an absolute path
• Label encoding failed: %v
• <combined HCL diagnostics from str.String()>

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