188

How can I stop a Gradle build after detecting a problem? I can use an assert, throw an exception, do a System.exit (bad idea), or use a dedicated function in Gradle (but I could not find one). What is the best way for Gradle (and why?).

6 Answers 6

144

I usually throw the relevant exception from the org.gradle.api package, for example InvalidUserDataException for when someone has entered something invalid, or GradleScriptException for more general errors.

If you want to stop the current task or action, and move on to the next, you can also throw a StopActionException

4
  • 7
    You can also use TaskExecutionException if a task does not execute successfully. (This is true according to the gradle 1.11 docs, I'm not sure when it was introduced.) Feb 24, 2014 at 19:45
  • 3
    are there any nice syntax options here? Consider kotlin's preconditions syntax: require(something != whatever) { "No good!" } as opposed to the more verbose and type-ee if(something != whatever){ throw new GradleException("No good!") }
    – Groostav
    Oct 20, 2016 at 19:51
  • 1
    The awful thing about GradleScriptException is that it requires a second parameter for a cause.
    – Hakanai
    May 25, 2017 at 5:06
  • ... Of course we are avoiding saying that this is "programming by exceptions"?! I have legacy coded written that way and it is a horror to maintain ... In the olde days the philosophy around make is that rules (task-s) succeeded or failed. I once tried return false -- Gradle just ignored it and continued to run.
    – will
    Jan 19, 2018 at 1:08
119

If you want to stop the build, throw:

throw new GradleException('error occurred')

or throw the subclasses for the above exception. Some of the subclass exceptions actually only fail the current task but continue with the build.

31

There is currently no dedicated method, although there have been discussions to add one.

The recommended way to stop a Gradle build is to throw an exception. Since Groovy doesn't have checked exceptions, and Gradle by default does not print the exception type, it's not that critical which exception is thrown. In build scripts, GradleException is often used, but a Groovy assertion also seems reasonable (depending on the circumstances and audience). What's important is to provide a clear message. Adding a cause (if available) helps for debugging (--stacktrace).

Gradle provides dedicated exception types StopExecutionException/StopActionException for stopping the current task/task action but continuing the build.

21

Another option if you don't have any desire to be able to catch the exception later on is to call the ant fail task. It's slightly easier to read in my opinion and you can give a nice message to the user without use of --stacktrace.

task (tarball, dependsOn: warAdmin) << {
    ant.fail('The sky is falling!!')
}

Gives you a message like:

* What went wrong:
Execution failed for task ':tarball'.
> The sky is falling!!

Probably you can catch this (perhaps it throws ant's BuildException?) but if that's a goal then I wouldn't use ant.fail. I'd just make it easy to see what exception to catch by throwing standard gradle exception as tim_yates suggested.

4
  • How do I set it up? Call it?
    – powder366
    Dec 20, 2013 at 11:51
  • 1
    just call ant.fail('message of your choice') no setup required
    – Gus
    Dec 22, 2013 at 17:59
  • 2
    It looks like the output of this is identical to using throw new GradleException("The sky is falling!!") (Gradle 3.4.1)
    – mgaert
    Nov 6, 2017 at 15:59
  • @mgaert I seem to recall that 4 years ago when I wrote this, the message printed did differ (but that's a long time and I don't feel like figuring out what version was current at that time and checking). Beyond that, IMHO ant.fail more clearly communicates the intent to fully stop the build, whereas the thrown exception reads as something that might be caught and handled.
    – Gus
    Nov 26, 2017 at 1:06
21

Throwing a simple GradleException works in stopping the build script. This works great for checking required environment setup.

GradleException('your message, why the script is stopped.')

Example:

if(null == System.getenv()['GRADLE_USER_HOME']) {
    throw new GradleException('Required GRADLE_USER_HOME environment variable not set.')
}
7

Here is a code fragment that tries to emulate how the Gradle javac task throws errors:

task myCommand(type:Exec) {

    ... normal task setup ....

    ignoreExitValue true
    standardOutput = new ByteArrayOutputStream()
    ext.output = { standardOutput.toString() }
    doLast {
        if (execResult.exitValue) {
            logger.error(output())
            throw new TaskExecutionException( it,
                new Exception( "Command '${commandLine.join(' ')}' failed; "
                              + "see task output for details." )
            )
        }
    }
}

When the command returns 0 there is no output. Any other value will print the standardOutput and halt the build.

NOTE: If your command writes to errorOutput as well, you may need to include that in the error log.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.