Jenkins "ClassCastException" on a pipeline step argument in CI

By Daniel Zoghalchali·Latchkey

When Jenkins binds named arguments to a step, a value whose type does not match what the step descriptor expects raises a ClassCastException. This differs from a Groovy cast: it happens inside the step argument coercion, not your own assignment.

What this error means

The build fails with java.lang.ClassCastException: class java.lang.String cannot be cast to class java.util.Map (or similar) in a stack pointing at DescribableModel / step argument instantiation.

java.lang.ClassCastException: class java.lang.String cannot be cast to
class java.util.Map (java.lang.String and java.util.Map are in module java.base)
	at org.jenkinsci.plugins.structs.describable.DescribableModel.instantiate

Common causes

A step parameter got the wrong shape

A step expecting a nested map of options received a plain string, so the structs binder cannot construct the model.

A list/map mix-up in step configuration

Passing a list where a single object is expected (or vice versa) for an argument fails the descriptor cast.

How to fix it

Pass the argument in the shape the step expects

1. Check the step documentation for the exact type of each named argument.
2. Wrap or restructure the value so a Map argument receives [key: value], a list receives [...].
3. Re-run after correcting the argument shape.

// expects a map, not a string:
archiveArtifacts artifacts: 'build/*.jar', fingerprint: true

How to prevent it

• Consult the Pipeline Steps reference for argument types before use.
• Build complex step arguments as explicit maps/lists in a variable.
• Test new step invocations in a scratch job.

Frequently asked questions

Related guides

References

• GitHub Actions documentation