jenkinsci/jenkins · error · IOException

Failed to join the process

Error message

Failed to join the process

What it means

Thrown by Proc.RemoteProc.join() when the underlying Future<Integer> completes exceptionally with an ExecutionException whose cause is NOT an IOException. IOException causes are unwrapped and rethrown directly; non-IO causes are wrapped in this generic IOException. RemoteProc wraps a process launched over a Jenkins Channel (remoting), so the future represents the remote process's exit code.

Source

Thrown at core/src/main/java/hudson/Proc.java:466

                if (this.isAlive()) { // Should never happen but this forces Proc to not be removed and early GC by escape analysis
                    // TODO: Report exceptions if they happen?
                    LOGGER.log(Level.WARNING, "Process {0} has not really finished after the kill() method execution", this);
                }
            }
        }

        @Override
        public int join() throws IOException, InterruptedException {
            try {
                return process.get();
            } catch (InterruptedException e) {
                LOGGER.log(Level.FINE, String.format("Join operation has been interrupted for the process %s. Killing the process", this), e);
                kill();
                throw e;
            } catch (ExecutionException e) {
                if (e.getCause() instanceof IOException)
                    throw (IOException) e.getCause();
                throw new IOException("Failed to join the process", e);
            } catch (CancellationException x) {
                return -1;
            } finally {
                if (this.isAlive()) { // Should never happen but this forces Proc to not be removed and early GC by escape analysis
                    LOGGER.log(Level.WARNING, "Process {0} has not really finished after the join() method completion", this);
                }
            }
        }

        @Override
        public boolean isAlive() throws IOException, InterruptedException {
            return !process.isDone();
        }

        @Override
        public InputStream getStdout() {
            return null;
        }

View on GitHub (pinned to 2e228ff40b)

Solutions

  1. Examine the cause chain (getCause()) of the thrown IOException — the real exception type and message reveal the remote failure.
  2. Check the agent's remoting logs (agent.jar console output or /var/log/jenkins/) for the matching stack trace.
  3. Verify remoting version compatibility between controller and agent — a mismatch can cause ClassNotFoundException over the channel.
  4. If the cause is an OutOfMemoryError, increase the agent JVM heap (-Xmx).
  5. If the channel was disconnected, ensure network stability between controller and agent and check agent keep-alive settings.
Defensive patterns

Strategy: try-catch

Try / catch

try {
    int exitCode = proc.join();
} catch (IOException e) {
    Throwable cause = e.getCause();
    if (cause != null) {
        LOGGER.log(Level.SEVERE, "Remote process failed: " + cause.getClass().getName() + ": " + cause.getMessage(), cause);
    } else {
        LOGGER.log(Level.SEVERE, "Process join failed", e);
    }
}

Prevention

When it happens

Trigger: The remote Future.get() throws ExecutionException; e.getCause() is checked — if it is an IOException, it is rethrown as-is; any other cause type (RuntimeException, Error, etc.) triggers this wrapper. This typically happens when the remote side throws an unexpected non-IO exception while executing the process.

Common situations: The agent channel is abruptly torn down due to a non-IO error; the remote process executor throws a RuntimeException (e.g., ClassNotFoundException for a callable sent over the channel); the agent JVM crashes or runs out of memory during process execution; a remoting protocol error surfaces as a non-IO exception.

Related errors

AI-assisted analysis of jenkinsci/jenkins@2e228ff40b (2026-08-14). Data as JSON: /api/errors/8e5d176f7a1d23dc. Report an issue: GitHub.