Introduction

Process 'command 'java'' finished with non-zero exit value 1 is a wrapper error, not the root cause. Gradle is telling you that some Java process it launched failed, and your real job is to identify which task started that process and what exception or configuration problem caused it to exit.

What the Message Actually Means

Exit code 1 is a generic failure code from the Java process. Gradle commonly shows it for tasks such as test, run, JavaExec, annotation processors, code generators, or Android tooling. The wording makes the failure look like a Gradle problem, but in many cases the Java application itself threw an exception and terminated.

The first step is therefore not changing random Gradle settings. The first step is making the failing task print a complete stack trace.

./gradlew build --stacktrace
./gradlew build --info
./gradlew build --debug

Usually --stacktrace is enough. It shows whether the failure came from compilation, tests, a missing class, bad JVM arguments, or an application crash.

Isolate the Failing Task

If build fails, rerun only the suspected task. That removes noise and gives you a smaller log.

./gradlew test --stacktrace
./gradlew run --stacktrace
./gradlew myCustomTask --stacktrace

For custom JavaExec tasks, inspect the command line, classpath, and arguments. A small configuration mistake can surface only as exit code 1.

1tasks.register('runTool', JavaExec) {
2    classpath = sourceSets.main.runtimeClasspath
3    mainClass = 'com.example.Tool'
4    args 'input.txt'
5    jvmArgs '-Xmx512m'
6}

If Tool throws an exception during startup, Gradle will only report that the Java process exited unsuccessfully until you read the process output.

Common Root Causes

The most common causes are ordinary Java failures:

• an exception thrown in main
• failing tests
• missing environment variables or input files
• wrong classpath or dependency version
• incompatible JDK version
• insufficient heap memory

Here is a minimal example of a program that will trigger the error because it exits with an exception.

1public class Tool {
2    public static void main(String[] args) {
3        if (args.length == 0) {
4            throw new IllegalArgumentException("Expected at least one argument");
5        }
6
7        System.out.println("Processing " + args[0]);
8    }
9}

If your Gradle task launches this class without arguments, Gradle will surface the failure as non-zero exit value 1.

Fix the Cause, Not the Symptom

Once the actual exception is visible, fix it in the relevant layer. If a test fails, repair the test or the production code. If the task cannot find a file, use an absolute or project-relative path. If the JDK is wrong, align Gradle's toolchain with the version your build expects.

1java {
2    toolchain {
3        languageVersion = JavaLanguageVersion.of(21)
4    }
5}

That toolchain block prevents a common class of failures where Gradle runs with one JDK locally and another JDK in CI.

Common Pitfalls

• Treating exit value 1 as the real error wastes time because it is only the final symptom.
• Running only gradlew build without --stacktrace often hides the useful part of the failure.
• Ignoring the specific failing task makes the log much harder to read.
• Assuming Gradle is broken when the launched Java program actually threw a normal exception leads to the wrong fix.
• Building on different JDK versions across machines creates failures that look random but are configuration drift.

Summary

• Exit value 1 means a Java process launched by Gradle failed.
• The real cause is usually in the task output, stack trace, or application exception.
• Use --stacktrace first, then rerun the individual failing task.
• Inspect JavaExec, test, and toolchain configuration before changing unrelated build logic.
• Fix the underlying exception or configuration mismatch rather than the generic Gradle message.