gradle/gradle · error · ProcessExecutionException

Unable to connect to the child process '%s'. It is likely th

Error message

Unable to connect to the child process '%s'.
It is likely that the child process have crashed - please find the stack trace in the build log.
This exception might occur when the build machine is extremely loaded.
The connection attempt hit a timeout after %.1f seconds (last known process state: %s, running: %s).

What it means

Gradle forks a separate JVM whenever work runs with process isolation (Worker API processIsolation, forked compilers/test workers). This ProcessExecutionException means the parent started the child process but never received the child's connection back within the connect timeout (configurable via setConnectTimeoutSeconds). In nearly all cases the child JVM crashed during startup or the machine was too loaded for the child to finish bootstrapping in time. The child's own stack trace, when present, appears earlier in the build log.

Source

Thrown at platforms/core-execution/worker-process-services/src/main/java/org/gradle/process/internal/worker/DefaultWorkerProcess.java:202

    }

    private void doStart() {
        lock.lock();
        try {
            running = true;
        } finally {
            lock.unlock();
        }

        execHandle.start();

        Date connectExpiry = new Date(System.currentTimeMillis() + connectTimeout);
        lock.lock();
        try {
            while (connection == null && running) {
                try {
                    if (!condition.awaitUntil(connectExpiry)) {
                        throw new ProcessExecutionException(format("Unable to connect to the child process '%s'.\n"
                                + "It is likely that the child process have crashed - please find the stack trace in the build log.\n"
                                + "This exception might occur when the build machine is extremely loaded.\n"
                                + "The connection attempt hit a timeout after %.1f seconds (last known process state: %s, running: %s).", execHandle, ((double) connectTimeout) / 1000, execHandle.getState(), running));
                    }
                } catch (InterruptedException e) {
                    throw UncheckedException.throwAsUncheckedException(e);
                }
            }
            if (connection == null) {
                if (processFailure != null) {
                    throw UncheckedException.throwAsUncheckedException(processFailure);
                } else {
                    throw new ProcessExecutionException(format("Never received a connection from %s.", execHandle));
                }
            }
        } finally {
            lock.unlock();
        }

View on GitHub (pinned to 534f27719b)

Solutions

1. Search upward in the build log for the child process's stack trace - the root cause is almost always logged there before this exception
2. Check the fork options (jvmArgs, executable, memory settings) passed to processIsolation/forkOptions and verify each flag is valid for the target JVM
3. Reduce machine load or free memory and rerun; this exception is explicitly documented as possible on extremely loaded machines
4. Raise the connect timeout via the worker process builder's setConnectTimeoutSeconds if the machine is legitimately slow
5. Verify the JVM used for forking (org.gradle.java.home / forkOptions.executable) is a complete, working JDK

try {
    workerExecutor.await();
} catch (WorkerExecutionException e) {
    if (e.getCause() instanceof ProcessExecutionException
            && e.getCause().getMessage().startsWith("Unable to connect to the child process")) {
        // transient under load: inspect build log for the child crash, then retry the task once
    } else { throw e; }
}

When it happens

Trigger: awaitConnection() in DefaultWorkerProcess: execHandle.start() succeeds, then the condition loop waits until connectExpiry; if 'connection' is still null while 'running' is still true when condition.awaitUntil(connectExpiry) returns false, this exception throws with the exec handle, timeout in seconds, last known process state and running flag. Typical API path: WorkerExecutor.processIsolation(...).submit(...) or any WorkerProcessBuilder-built fork whose child JVM never completes the handshake.

Common situations: Child JVM dies at bootstrap (invalid jvmArgs for the selected JDK, bad main class, broken bootstrap jar), classpath/argfile problems on Windows, severe CI load or memory pressure slowing the child past the timeout, antivirus slowing process spawn, or the child being OOM-killed before connecting.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Never received a connection from %s.
• Could not initialise system classpath.
• Could not create an instance of '{securityManagerType}' spec
• Cannot load worker action's class
• Unsupported worker JDK version. Required: %s. Current: %s

AI-assisted analysis of gradle/gradle@534f27719b (2026-08-22). Data as JSON: /api/errors/cd523c06eb407481. Report an issue: GitHub.