Recommended way to stop a Gradle build

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?).

I usually throw the relevant exception from the [org.gradle.api package](https://docs.gradle.org/current/javadoc/org/gradle/api/package-summary.html "See the "Exception Summary" table"), 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

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.

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.

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.

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.')
}

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.