Jenkins – unable to resolve class utilities.MyUtilities

It’s more than likely, you start trying to import external classes/files if you use Jenkins Job DSL Plugin. When your jobs grow to tens or hundreds of projects, some code will be common in some places. So, you will read the documentation, check the community forums, try to find out the best way to simplify your life. And you find it. You will find very quickly, that you can import classes from external files. Jenkins DSL uses Groovy, and Groovy is based on Java, after all, so it’s not a surprise. After you find that information you will try to implement that. And this is the time, in which you might face the following error: unable to resolve class utilities.MyUtilities. Of course, it will be your class and package name at the end of the error message. Oops. Not good.

Why does unable to resolve class utilities.MyUtilities appear?

There are three main, potential reasons:

  1. unproperly created class/package
  2. you are using the Job DSL Plugin in version 1.60 or above
  3. you are using the Job DSL Plugin in version 1.67 or above AND you are not using the Groovy sandbox

Let’s see all of these reasons in details.

Unproperly created class/package

When I write “unproperly created”, it means both created and imported. Please take a look at the documentation example (you can find that here):

unable to resolve class utilities.MyUtilities reason

So, as you can see, utilities is a reference to the directory contains a MyUtilities.groovy file. The first sentence suggests that mentioned directory should be placed at the same level as your DSL script. So the proper tree should look like this:

And for that matter, please be careful when you create a class. You should avoid using a public class access modifier. It’s the default modifier for any class in Groovy. I saw that in some cases if you type public before a class statement, you might encounter the unable to resolve class utilities.MyUtilities error too.

You are using the Job DSL Plugin in version 1.60 or above

That’s the second probable reason. Since Job DSL Plugin version 1.60 importing classes from the job’s workspace is not allowed anymore. According to the release notes, neither importing classes from the workspace nor the “Additional Classpath” usage is possible.

To avoid loading arbitrary code from the workspace without approval, the script directory is not added to the classpath and additional classpath entries are not supported when security is enabled. Thus importing classes from the workspace is not possible and the “Additional Classpath” option is not available.

So, as you can see, it’s not possible to import a class. But there is one way which can help you – disabling Job DSL Script Security. Of course, it’s not recommended. However, in some very special situations, it could be excused. Anyway, try to avoid this – you have one MORE way. Just upgrade your plugin to version 1.67 (at least). This version is the reason and the fix at the same time.

You are using the Job DSL Plugin in version 1.67 or above AND you are not using the Groovy sandbox

Yes, I mentioned this point to be the potential solution, but it can also the reason for your problem. Even if you upgrade your plugin to at least version 1.67, your problem may not be solved, because of some security restriction introduced to the plugin. Even though there is a possibility to add our own classpath, we cannot do that without Groovy sandbox when Script Security is enabled. It means that if you try to run your DSL script without sandbox, you also will not be able to use your classes. You can still disable Script Security, but it’s not recommended of course. If you want to see more about Script Security, please visit official GitHub repository.

The Wiki page you will be redirected to contains not only some basic information about Script Security but also a simple tutorial. You can find how to configure Jenkins to use Groovy sandboxes in general. I will try to create a more detailed tutorial, step by step, but I’m not sure when it will be possible. 🙂

2 Replies to “Jenkins – unable to resolve class utilities.MyUtilities”

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.