jenkinsci/jenkins · error · CmdLineException

Cannot resolve the value for the parameter '%s'.

Error message

Cannot resolve the value for the parameter '%s'.

What it means

Thrown as a CmdLineException when a ParameterDefinition.createValue(StaplerRequest, String) returns null for the given value string. This means the parameter definition recognized its name but could not parse/resolve the provided value into a valid ParameterValue.

Source

Thrown at core/src/main/java/hudson/cli/BuildCommand.java:124

            ParametersDefinitionProperty pdp = job.getProperty(ParametersDefinitionProperty.class);
            if (pdp == null)
                throw new IllegalStateException(job.getFullDisplayName() + " is not parameterized but the -p option was specified.");

            //TODO: switch to type annotations after the migration to Java 1.8
            List<ParameterValue> values = new ArrayList<>();

            for (Map.Entry<String, String> e : parameters.entrySet()) {
                String name = e.getKey();
                ParameterDefinition pd = pdp.getParameterDefinition(name);
                if (pd == null) {
                    String nearest = EditDistance.findNearest(name, pdp.getParameterDefinitionNames());
                    throw new CmdLineException(null, nearest == null ?
                            String.format("'%s' is not a valid parameter.", name) :
                            String.format("'%s' is not a valid parameter. Did you mean %s?", name, nearest));
                }
                ParameterValue val = pd.createValue(this, Util.fixNull(e.getValue()));
                if (val == null) {
                    throw new CmdLineException(null, String.format("Cannot resolve the value for the parameter '%s'.", name));
                }
                values.add(val);
            }

            // handle missing parameters by adding as default values ISSUE JENKINS-7162
            for (ParameterDefinition pd : pdp.getParameterDefinitions()) {
                if (parameters.containsKey(pd.getName()))
                    continue;

                // not passed in use default
                ParameterValue defaultValue = pd.getDefaultParameterValue();
                if (defaultValue == null) {
                    throw new CmdLineException(null, String.format("No default value for the parameter '%s'.", pd.getName()));
                }
                values.add(defaultValue);
            }

            a = new ParametersAction(values);

View on GitHub (pinned to 2e228ff40b)

Solutions

  1. Check the parameter type in the job configuration and provide a value in the expected format.
  2. For Choice parameters, verify the value matches one of the defined choices exactly (case-sensitive).
  3. For Boolean parameters, use 'true' or 'false'.
  4. For File parameters, ensure the file exists and the path is correct.
Defensive patterns

Strategy: validation

Validate before calling

// Validate parameter value type before calling createValue
ParameterDefinition pd = pdp.getParameterDefinition(name);
if (pd != null) {
    ParameterValue val = pd.createValue(Util.fixNull(value));
    if (val == null) {
        throw new AbortException("Value '" + value + "' is not valid for parameter '" + name + "' (type: " + pd.getType() + ")");
    }
}

Try / catch

try {
    // build command run()
} catch (CmdLineException e) {
    if (e.getMessage().contains("Cannot resolve the value")) {
        stderr.println(e.getMessage());
        stderr.println("Check the parameter type and expected format in the job configuration.");
        return 1;
    }
    throw e;
}

Prevention

When it happens

Trigger: pd.createValue(this, Util.fixNull(e.getValue())) returns null — the value string does not match the parameter type's expected format or constraints. For example, a BooleanParameterDefinition receiving an unparseable string, or a ChoiceParameterDefinition receiving a value not in the choices list.

Common situations: Passing 'yes' or '1' to a boolean parameter that expects 'true'/'false' (depending on the implementation); passing a value not in a Choice parameter's options; passing an invalid file path to a File parameter; passing a malformed string to a Run parameter; passing null or empty for a parameter that requires a value.

Related errors

AI-assisted analysis of jenkinsci/jenkins@2e228ff40b (2026-08-14). Data as JSON: /api/errors/40d529e764a7588d. Report an issue: GitHub.