hashicorp/nomad · error

failed to decode driver config: %v

Error message

failed to decode driver config: %v

What it means

StartTask decodes the task's driver-specific configuration block into the driver's TaskConfig struct via cfg.DecodeDriverConfig. This error wraps whatever decoding failure occurred (unknown fields, type mismatches, malformed HCL/JSON in the job's config stanza).

Source

Thrown at drivers/qemu/driver.go:464

			if strings.HasPrefix(strings.TrimSpace(arg), "-") {
				if _, ok := allowed[arg]; !ok {
					return fmt.Errorf("%q is not in args_allowlist", arg)
				}
			}
		}
	}
	return nil
}

func (d *Driver) StartTask(cfg *drivers.TaskConfig) (*drivers.TaskHandle, *drivers.DriverNetwork, error) {
	if _, ok := d.tasks.Get(cfg.ID); ok {
		return nil, nil, fmt.Errorf("taskConfig with ID '%s' already started", cfg.ID)
	}

	var driverConfig TaskConfig

	if err := cfg.DecodeDriverConfig(&driverConfig); err != nil {
		return nil, nil, fmt.Errorf("failed to decode driver config: %v", err)
	}

	// ensure that PortMap variables are populated early on
	cfg.Env = taskenv.SetPortMapEnvs(cfg.Env, driverConfig.PortMap)

	handle := drivers.NewTaskHandle(taskHandleVersion)
	handle.Config = cfg

	if err := validateEmulator(driverConfig.Emulator, d.config.EmulatorsAllowList); err != nil {
		return nil, nil, err
	}

	if err := validateArgs(d.config.ArgsAllowList, driverConfig.Args); err != nil {
		return nil, nil, err
	}

	// Get the image source
	vmPath := driverConfig.ImagePath

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Inspect the wrapped %v detail in the error message to identify the offending field, then fix the key name or value type in the job's config block.
2. Validate the job with 'nomad job validate' before submitting to catch decode errors early.
3. Align the config with the current qemu driver schema for your Nomad version (docs: drivers/qemu).

Example fix

// before (wrong type)
config { image_path = "..." memory = "1024" } // memory not a TaskConfig field
// after
config { image_path = "..." }

var probe map[string]interface{}
if err := hclDecodeInto(&probe, rawConfig); err != nil {
    return fmt.Errorf("malformed qemu config block: %w", err)
}
// check required keys/types before calling StartTask

_, _, err := d.StartTask(cfg)
if err != nil && strings.Contains(err.Error(), "failed to decode driver config") {
    return fmt.Errorf("check the task's qemu config block against driver schema: %w", err)
}

When it happens

Trigger: StartTask when the job's task config stanza cannot be decoded into qemu TaskConfig — e.g. a field with the wrong type (string where int expected), an unrecognized key under the qemu driver config, or a malformed value.

Common situations: Job spec renames or typos a qemu config field (e.g. 'image_path' misspelled); passing a non-string where the schema expects one; upgrading Nomad so previously tolerated fields become rejected; copy-pasting config from another driver.

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 decode driver config: %v
• failed to decode driver config: %v
• envoy must be used as connect sidecar or gateway
• QEMU graceful shutdown is unsupported on the Windows platfor
• Disconnect cannot be configured with both lost_after and sto

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