jenkinsci/jenkins · error · IllegalStateException

{} is not parameterized but the -p option was specified.

Error message

{} is not parameterized but the -p option was specified.

What it means

Thrown by BuildCommand.run() when the user supplies build parameters via -p but the target job has no ParametersDefinitionProperty (i.e., the job is not parameterized). This is an IllegalStateException indicating a mismatch between user input and job configuration.

Source

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

    public Map<String, String> parameters = new HashMap<>();

    @Option(name = "-v", usage = "Prints out the console output of the build. Use with -s")
    public boolean consoleOutput = false;

    @Option(name = "-r") @Deprecated
    public int retryCnt = 10;

    protected static final String BUILD_SCHEDULING_REFUSED = "Build scheduling Refused by an extension, hence not in Queue.";

    @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);

View on GitHub (pinned to 2e228ff40b)

Solutions

  1. Enable parameterization on the job: in job configuration, check 'This project is parameterized' and add the parameter definitions.
  2. Remove the -p arguments from the CLI command if the job is intentionally non-parameterized.
  3. If the job was recently changed, update the calling script or CI integration to match the current job configuration.
Defensive patterns

Strategy: validation

Validate before calling

// Check if job is parameterized before passing -p
ParametersDefinitionProperty pdp = job.getProperty(ParametersDefinitionProperty.class);
if (pdp == null && !parameters.isEmpty()) {
    throw new AbortException(job.getFullDisplayName() + " is not parameterized. Remove -p or add parameters to the job.");
}

Type guard

public static boolean isParameterized(Job<?, ?> job) {
    return job.getProperty(ParametersDefinitionProperty.class) != null;
}

Try / catch

try {
    // build command run()
} catch (IllegalStateException e) {
    if (e.getMessage().contains("is not parameterized")) {
        stderr.println(e.getMessage());
        stderr.println("Enable 'This project is parameterized' in job configuration.");
        return 1;
    }
    throw e;
}

Prevention

When it happens

Trigger: The parameters map (populated from -p CLI arguments) is non-empty, but job.getProperty(ParametersDefinitionProperty.class) returns null.

Common situations: Calling 'jenkins-cli build <job> -p KEY=VALUE' on a freestyle job that has no 'This project is parameterized' checkbox enabled; calling on a Pipeline job without parameters defined; job parameters were removed after a script was written that still passes -p.

Related errors

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