apache/beam · error · TimeoutException

Timeout waiting for Python service startup after

Error message

Timeout waiting for Python service startup after ${elapsed} milliseconds.

What it means

PythonService.waitForPort polls the expansion service host/port (via socket connect) with exponentially increasing backoff until a deadline. If the service never accepts a connection before the timeout, the library throws TimeoutException reporting elapsed milliseconds. It indicates the Python expansion service did not start or is unreachable at the given address.

Solutions

Check the expansion service logs/stderr to see why it did not start or crashed
Increase the waitForPort timeout parameter to accommodate slow startup
Verify the host:port is correct and reachable (telnet/nc host port) from the JVM host
Ensure a suitable Python and the beam package are installed so the service can launch

Example fix

// before
PythonService.waitForPort("localhost", 5000, Duration.standardSeconds(30));
// after
PythonService.waitForPort("localhost", 5000, Duration.standardMinutes(5));

Defensive patterns

Strategy: retry

Validate before calling

try (var s = new java.net.Socket()) {
  s.connect(new java.net.InetSocketAddress(host, port), 2000); // probe before expanding
} catch (IOException e) { /* service not up yet: increase timeout or check logs */ }

Try / catch

try {
  PythonService.waitForPort(host, port, timeout);
} catch (TimeoutException e) {
  // inspect service logs, verify address, optionally retry with a longer timeout
}

Prevention

Give slow environments a generous waitForPort timeout
Confirm the expansion service process is alive and listening before expansion
Verify host:port reachability with nc/telnet from the JVM host
Watch service stderr for startup crashes (missing packages, bad python)

When it happens

Trigger: Expansion service process fails to launch (bad python, missing packages); service listens on a different host/port than specified; firewall blocks the port; startup simply exceeds the timeout on slow machines; address format or port typo.

Common situations: Slow CI runners exceeding default startup timeout; service crashed during startup leaving nothing to connect to; connecting to wrong host in containerized setups; port already bound by a dead process.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

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

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/abcfef91f807f47f. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/extensions/python/src/main/java/org/apache/beam/sdk/extensions/python/PythonService.java:192

        // ignore
      }
    }
  }

  public static void waitForPort(String host, int port, int timeoutMs)
      throws TimeoutException, InterruptedException {
    long start = System.currentTimeMillis();
    long duration = 10;
    while (System.currentTimeMillis() - start < timeoutMs) {
      try {
        new Socket(host, port).close();
        return;
      } catch (IOException exn) {
        Thread.sleep(duration);
        duration = (long) (duration * 1.2);
      }
    }
    throw new TimeoutException(
        "Timeout waiting for Python service startup after "
            + (System.currentTimeMillis() - start)
            + " milliseconds.");
  }
}

View on GitHub (pinned to 12126d8942)