hashicorp/nomad · error

invalid value for %q: %w

Error message

invalid value for %q: %w

What it means

After reading each mkdir parameter, decodeMkdirParams converts its string value (strconv.Atoi for uid/gid, parsing for mode/path) and, if that conversion (or the unknown-parameter error from the default case) fails, returns this wrapped error naming the offending parameter. Note that the "unknown mkdir parameter" error from the default case is also routed through this wrapper, so this message can carry that cause too. It means a parameter key was recognized but its value could not be parsed into the expected numeric type.

Source

Thrown at client/hostvolumemanager/host_volume_plugin.go:195

	for param, val := range in {
		switch param {
		case "mode":
			// mode needs special treatment - it's octal. note that this does
			// not check whether it's a *reasonable* mode for a directory.
			// that will be discovered during MkdirAll and subsequent usage
			// by workloads (which we cannot predict).
			var number uint64
			number, err = strconv.ParseUint(val, 8, 32)
			out.Mode = os.FileMode(number)
		case "uid":
			out.Uid, err = strconv.Atoi(val)
		case "gid":
			out.Gid, err = strconv.Atoi(val)
		default:
			err = fmt.Errorf("unknown mkdir parameter: %q", param)
		}
		if err != nil {
			return out, fmt.Errorf("invalid value for %q: %w", param, err)
		}
	}

	return out, nil
}

func (p *HostVolumePluginMkdir) Delete(_ context.Context, req *cstructs.ClientHostVolumeDeleteRequest) error {
	path := filepath.Join(p.VolumesDir, req.ID)
	log := p.log.With(
		"operation", "delete",
		"volume_id", req.ID,
		"path", path)
	log.Debug("running plugin")

	err := os.RemoveAll(path)
	if err != nil {
		log.Error("error with plugin", "error", err)
		return err

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Supply numeric values: mode as an octal number string (e.g. "0755" or "493"), uid/gid as integer strings (e.g. "1000").
2. Check the %q in the wrapped message to see which parameter value failed, and inspect the raw value including hidden whitespace.
3. Fix templating so unset variables do not produce empty strings; validate inputs before calling Create.
4. If the cause is 'unknown mkdir parameter', rename the key per error 933's fix.

Example fix

// before
params := map[string]string{"path": "/vols/data", "mode": "rwxr-xr-x", "uid": "alice"}

// after
params := map[string]string{"path": "/vols/data", "mode": "0755", "uid": "1000"}

func validateMkdirValues(params map[string]string) error {
    for _, k := range []string{"mode", "uid", "gid"} {
        if v, ok := params[k]; ok {
            if _, err := strconv.Atoi(v); err != nil {
                return fmt.Errorf("parameter %q must be numeric, got %q", k, v)
            }
        }
    }
    return nil
}

if err != nil && strings.Contains(err.Error(), "invalid value for") {
    re := regexp.MustCompile(`invalid value for "([^"]+)"`)
    if m := re.FindStringSubmatch(err.Error()); m != nil {
        log.Error("fix numeric value for parameter", "param", m[0])
    }
}

When it happens

Trigger: Calling Create with a params map where "mode", "uid", or "gid" has a non-numeric string value — e.g. mode "rwxr-xr-x", uid "alice", gid "" — or where an unrecognized key triggered the default-case error which is then wrapped as invalid value.

Common situations: Users passing symbolic permission strings instead of octal numbers; putting a username instead of a numeric uid; empty-string values from templating/variable interpolation leaving a parameter unset; misconfigured job variable producing "0755\n" with stray whitespace.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• unknown mkdir parameter: %q
• ErrPluginNotExecutable
• ErrVolumeNameExists
• PluginID is required
• VolumeID is required

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