hashicorp/nomad · error

%q is not in args_allowlist

Error message

%q is not in args_allowlist

What it means

validateArgs enforces the plugin-level args_allowlist: every QEMU command-line argument passed via the task config that starts with '-' (after trimming whitespace) must be an exact key in the allowlist map built from pluginConfigAllowList. Nomad throws this to prevent tasks from injecting arbitrary QEMU flags (e.g. -drive with host paths, -netdev, monitor sockets) that could compromise the host.

Source

Thrown at drivers/qemu/driver.go:448

			return fmt.Errorf("'%s' is not an allowed emulator", emulator)
		}
	}
	return nil
}

// validateArgs ensures that all QEMU command line params are in the
// allowlist. This function must be called after all interpolation has
// taken place.
func validateArgs(pluginConfigAllowList, args []string) error {
	if len(pluginConfigAllowList) > 0 {
		allowed := map[string]struct{}{}
		for _, arg := range pluginConfigAllowList {
			allowed[arg] = struct{}{}
		}
		for _, arg := range args {
			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)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add the offending flag (the exact string including '-') to args_allowlist in the client's plugin configuration and restart the Nomad client.
2. Remove or reword the argument in the job's config args so it matches an already-allowed flag exactly (case- and whitespace-exact).
3. Ask the cluster operator to widen the allowlist if the flag is legitimately required.

Example fix

// client.hcl (before)
plugin "qemu" { config { args_allowlist = ["-m", "-smp"] } }
// after
plugin "qemu" { config { args_allowlist = ["-m", "-smp", "-cpu"] } }

allowlist := map[string]struct{}{"-m": {}, "-smp": {}, "-cpu": {}}
for _, a := range cfg.Args {
    if strings.HasPrefix(strings.TrimSpace(a), "-") {
        if _, ok := allowlist[a]; !ok {
            return fmt.Errorf("arg %q must be added to args_allowlist", a)
        }
    }
}

func argsInAllowlist(args []string, allowlist []string) bool {
    set := make(map[string]struct{}, len(allowlist))
    for _, a := range allowlist { set[a] = struct{}{} }
    for _, a := range args {
        if strings.HasPrefix(strings.TrimSpace(a), "-") {
            if _, ok := set[a]; !ok { return false }
        }
    }
    return true
}

_, _, err := d.StartTask(cfg)
if err != nil && strings.Contains(err.Error(), "is not in args_allowlist") {
    // extract flagged arg from error and update client plugin config
}

When it happens

Trigger: StartTask (or TestArgsAllowList in tests) when the task config's 'args' array contains a flag beginning with '-' that is not exactly present in the driver plugin's args_allowlist configuration; note the exact-match check (map lookup, no wildcard/prefix matching of values).

Common situations: Adding a new QEMU flag to a job (e.g. -cpu host) without updating args_allowlist; the flag has a value like '-m 1024' and the allowlist only contains '-m' but the task passes the flag and value as one string; whitespace/typo differences make TrimSpace mismatch.

Related errors

• image_path is not in the allowed paths
• running container as ContainerAdmin is unsafe; change the co
• QEMU graceful shutdown is unsupported on the Windows platfor
• ACL token not found
• running as user %q is disallowed

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