hashicorp/nomad · error

image_path must be set

Error message

image_path must be set

What it means

The qemu driver requires the image_path option to point at the VM disk image (e.g. an .img/.qcow2 file) inside an allowed directory. This error is thrown when image_path is empty, i.e. the job did not set the required option. A companion check also rejects paths outside the configured image_paths directories.

Source

Thrown at drivers/qemu/driver.go:484

	// 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
	if vmPath == "" {
		return nil, nil, fmt.Errorf("image_path must be set")
	}
	vmID := filepath.Base(vmPath)

	if !isAllowedImagePath(d.config.ImagePaths, cfg.AllocDir, vmPath) {
		return nil, nil, fmt.Errorf("image_path is not in the allowed paths")
	}

	// Parse configuration arguments
	// Create the base arguments
	emulator := "x86_64"
	if driverConfig.Emulator != "" {
		// COMPAT: TrimPrefix to support full emulator name
		// which was required in 1.11.1.
		emulator = strings.TrimPrefix(driverConfig.Emulator, "qemu-system-")

	}
	accelerator := "tcg"
	if driverConfig.Accelerator != "" {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set image_path in the task's qemu config block to an absolute path of the VM image on the client host.
2. Verify any variable/parameter interpolation feeding image_path resolves non-empty (check with 'nomad job inspect').
3. If the image is not already on the client, note that the artifact stanza cannot download it (a known driver limitation) — place the image in a directory listed in the client's image_paths.

Example fix

// before
config { emulator = "qemu-system-x86_64" } // image_path missing
// after
config { emulator = "qemu-system-x86_64" image_path = "/opt/vms/linux.img" }

if cfg.ImagePath == "" {
    return errors.New("qemu task config must set image_path")
}
if !strings.HasSuffix(cfg.ImagePath, ".img") && !strings.HasSuffix(cfg.ImagePath, ".qcow2") {
    return fmt.Errorf("suspicious image_path %q", cfg.ImagePath)
}

func hasImagePath(c TaskConfig) (string, bool) {
    if c.ImagePath == "" { return "", false }
    return c.ImagePath, true
}

_, _, err := d.StartTask(cfg)
if err != nil && strings.Contains(err.Error(), "image_path") {
    // job is missing image_path or path not under image_paths; fix config
}

When it happens

Trigger: StartTask when driverConfig.ImagePath is the empty string — the task's qemu config block omitted image_path or set it to "".

Common situations: Forgetting image_path in a new qemu task; variable interpolation in the job resolved to an empty string (e.g. missing meta/var); template rendering failed silently leaving the field blank.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• QEMU graceful shutdown is unsupported on the Windows platfor
• '%s' is not an allowed emulator
• %q is not in args_allowlist
• taskConfig with ID '%s' already started
• failed to decode driver config: %v

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