What causes "QEMU memory assignment out of bounds" in hashicorp/nomad?

Set resources.memory to a value between 128 and 4000000 MB in the task's resources block.

QEMU memory assignment out of bounds

Error message

QEMU memory assignment out of bounds

What it means

Before building QEMU's -m memory argument, StartTask bounds-checks the task's Memory.MemoryMB from the resources block: it must be between 128 MB and 4,000,000 MB. Values outside that range make StartTask fail. This catches invalid resource declarations (including missing/zero memory, which lands below the 128 MB floor) before spawning the VM.

Source

Thrown at drivers/qemu/driver.go:512

	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 != "" {
		accelerator = driverConfig.Accelerator
	}
	machineType := "pc"
	if driverConfig.MachineType != "" {
		machineType = driverConfig.MachineType
	}

	mb := cfg.Resources.NomadResources.Memory.MemoryMB
	if mb < 128 || mb > 4000000 {
		return nil, nil, fmt.Errorf("QEMU memory assignment out of bounds")
	}
	mem := fmt.Sprintf("%dM", mb)

	absPath, err := GetAbsolutePath(fmt.Sprintf("qemu-system-%s", emulator))
	if err != nil {
		return nil, nil, err
	}

	driveInterface := "ide"
	if driverConfig.DriveInterface != "" {
		driveInterface = driverConfig.DriveInterface
	}
	if !isAllowedDriveInterface(driveInterface) {
		return nil, nil, fmt.Errorf("Unsupported drive_interface")
	}

	args := []string{
		absPath,

View on GitHub (pinned to 482b49bf1a)

Solutions

Set resources.memory to a value between 128 and 4000000 MB in the task's resources block.
If the VM needs more than ~4 TB, split workloads or use a different driver/host configuration, since the driver hard-caps at 4000000 MB.
Check interpolated values (variables/templating) that produce 0 or an absurdly large number.

Example fix

// before
resources {
  cpu    = 500
}
// after
resources {
  cpu    = 500
  memory = 512
}

Defensive patterns

Strategy: validation

Validate before calling

function validateQemuMemory(resources) {
  const mb = resources?.NomadResources?.Memory?.MemoryMB ?? resources?.memory ?? 0;
  if (mb < 128 || mb > 4000000) {
    throw new Error(`QEMU memory assignment out of bounds: got ${mb} MB, need 128..4000000`);
  }
}
validateQemuMemory(taskJson.resources);

Type guard

function hasValidMemoryMB(res) {
  const mb = res?.NomadResources?.Memory?.MemoryMB;
  return typeof mb === "number" && Number.isFinite(mb) && mb >= 128 && mb <= 4000000;
}

Try / catch

try {
  await nomad.jobs.register(job);
} catch (e) {
  if (String(e.message).includes("QEMU memory assignment out of bounds")) {
    console.error("Set resources.memory to 128..4000000 MB");
  }
  throw e;
}

Prevention

Always declare an explicit memory value in the resources block for QEMU tasks.
Lint job specs: assert MemoryMB within [128, 4000000] in CI.
Remember units are MB; convert GB with *1024 before templating.
Watch for template interpolation returning empty string (yields 0).

When it happens

Trigger: Starting a QEMU task whose resources.memory = 0 or missing (below 128); resources.memory > 4000000 MB (over 4 TB); a misconfigured template or variable interpolation yielding a huge or zero MemoryMB.

Common situations: Task author forgets the memory stanza entirely (defaults to 0); copy-paste of a docker task config with tiny/absent memory; accidentally specifying memory in KB or bytes; deliberate test of an extreme value above 4,000,000.

Related errors

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