{"record":{"id":"3aec7bad559d0004","repo":"hashicorp/nomad","slug":"image-path-must-be-set","errorCode":null,"errorMessage":"image_path must be set","messagePattern":"image_path must be set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/qemu/driver.go","lineNumber":484,"sourceCode":"\n\t// ensure that PortMap variables are populated early on\n\tcfg.Env = taskenv.SetPortMapEnvs(cfg.Env, driverConfig.PortMap)\n\n\thandle := drivers.NewTaskHandle(taskHandleVersion)\n\thandle.Config = cfg\n\n\tif err := validateEmulator(driverConfig.Emulator, d.config.EmulatorsAllowList); err != nil {\n\t\treturn nil, nil, err\n\t}\n\n\tif err := validateArgs(d.config.ArgsAllowList, driverConfig.Args); err != nil {\n\t\treturn nil, nil, err\n\t}\n\n\t// Get the image source\n\tvmPath := driverConfig.ImagePath\n\tif vmPath == \"\" {\n\t\treturn nil, nil, fmt.Errorf(\"image_path must be set\")\n\t}\n\tvmID := filepath.Base(vmPath)\n\n\tif !isAllowedImagePath(d.config.ImagePaths, cfg.AllocDir, vmPath) {\n\t\treturn nil, nil, fmt.Errorf(\"image_path is not in the allowed paths\")\n\t}\n\n\t// Parse configuration arguments\n\t// Create the base arguments\n\temulator := \"x86_64\"\n\tif driverConfig.Emulator != \"\" {\n\t\t// COMPAT: TrimPrefix to support full emulator name\n\t\t// which was required in 1.11.1.\n\t\temulator = strings.TrimPrefix(driverConfig.Emulator, \"qemu-system-\")\n\n\t}\n\taccelerator := \"tcg\"\n\tif driverConfig.Accelerator != \"\" {","sourceCodeStart":466,"sourceCodeEnd":502,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/qemu/driver.go#L466-L502","documentation":"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.","triggerScenarios":"StartTask when driverConfig.ImagePath is the empty string — the task's qemu config block omitted image_path or set it to \"\".","commonSituations":"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.","solutions":["Set image_path in the task's qemu config block to an absolute path of the VM image on the client host.","Verify any variable/parameter interpolation feeding image_path resolves non-empty (check with 'nomad job inspect').","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."],"exampleFix":"// before\nconfig { emulator = \"qemu-system-x86_64\" } // image_path missing\n// after\nconfig { emulator = \"qemu-system-x86_64\" image_path = \"/opt/vms/linux.img\" }","handlingStrategy":"validation","validationCode":"if cfg.ImagePath == \"\" {\n    return errors.New(\"qemu task config must set image_path\")\n}\nif !strings.HasSuffix(cfg.ImagePath, \".img\") && !strings.HasSuffix(cfg.ImagePath, \".qcow2\") {\n    return fmt.Errorf(\"suspicious image_path %q\", cfg.ImagePath)\n}","typeGuard":"func hasImagePath(c TaskConfig) (string, bool) {\n    if c.ImagePath == \"\" { return \"\", false }\n    return c.ImagePath, true\n}","tryCatchPattern":"_, _, err := d.StartTask(cfg)\nif err != nil && strings.Contains(err.Error(), \"image_path\") {\n    // job is missing image_path or path not under image_paths; fix config\n}","preventionTips":["Always set image_path in qemu task configs; lint job templates for it","Ensure interpolated variables feeding image_path resolve non-empty","Place images under a directory listed in the client's image_paths","Remember artifacts cannot download VM images — provision them out-of-band"],"tags":["qemu","nomad","missing-config","image-path"],"backgroundTag":"missing-required-config-field","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"}