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
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
-
7You 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
-
3are there any nice syntax options here? Consider kotlin's preconditions syntax:
require(something != whatever) { "No good!" }
as opposed to the more verbose and type-eeif(something != whatever){ throw new GradleException("No good!") }
– GroostavOct 20, 2016 at 19:51 -
1The awful thing about
GradleScriptException
is that it requires a second parameter for a cause.– HakanaiMay 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 thatrules
(task-s) succeeded or failed. I once triedreturn false
-- Gradle just ignored it and continued to run.– willJan 19, 2018 at 1:08
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.
-
-
1
-
2It looks like the output of this is identical to using
throw new GradleException("The sky is falling!!")
(Gradle 3.4.1)– mgaertNov 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.– GusNov 26, 2017 at 1:06
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.