jenkinsci/jenkins · error · CmdLineException

'%s' is not a valid parameter.

Error message

'%s' is not a valid parameter.

What it means

Thrown as a CmdLineException when a parameter name passed via -p does not match any defined ParameterDefinition, and EditDistance.findNearest returns null (no close match exists among the defined parameter names). The message includes only the invalid parameter name.

Source

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

    @Override
    protected int run() throws Exception {
        job.checkPermission(Item.BUILD);

        ParametersAction a = null;
        if (!parameters.isEmpty()) {
            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) {

View on GitHub (pinned to 2e228ff40b)

Solutions

  1. List the job's defined parameters: 'jenkins-cli build <job>' without -p, or check the job's parameter definitions in the UI.
  2. Correct the parameter name in the -p argument to match a defined parameter exactly.
  3. If the parameter was renamed, update the calling script to use the new name.
Defensive patterns

Strategy: validation

Validate before calling

// Validate parameter names against defined parameters
ParametersDefinitionProperty pdp = job.getProperty(ParametersDefinitionProperty.class);
if (pdp != null) {
    for (String name : parameters.keySet()) {
        if (pdp.getParameterDefinition(name) == null) {
            throw new AbortException("Parameter '" + name + "' is not defined on job. Defined: " + pdp.getParameterDefinitionNames());
        }
    }
}

Type guard

public static boolean isValidParameterName(ParametersDefinitionProperty pdp, String name) {
    return pdp.getParameterDefinition(name) != null;
}

Try / catch

try {
    // build command run()
} catch (CmdLineException e) {
    if (e.getMessage().contains("is not a valid parameter")) {
        stderr.println(e.getMessage());
        stderr.println("Run with --help or check the job's parameter definitions.");
        return 1;
    }
    throw e;
}

Prevention

When it happens

Trigger: pdp.getParameterDefinition(name) returns null for the given -p key, and EditDistance.findNearest(name, pdp.getParameterDefinitionNames()) returns null — meaning no defined parameter name is within edit-distance threshold of the provided name.

Common situations: Significant typo in parameter name; parameter was renamed or removed from the job; copy-paste error from documentation or another job's parameters; wrong job targeted.

Related errors

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