{"record":{"id":"abcfef91f807f47f","repo":"apache/beam","slug":"timeout-waiting-for-python-service-startup-after-elapsed","errorCode":null,"errorMessage":"Timeout waiting for Python service startup after ${elapsed} milliseconds.","messagePattern":"Timeout waiting for Python service startup after (.+?) milliseconds\\.","errorType":"exception","errorClass":"TimeoutException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/python/src/main/java/org/apache/beam/sdk/extensions/python/PythonService.java","lineNumber":192,"sourceCode":"        // ignore\n      }\n    }\n  }\n\n  public static void waitForPort(String host, int port, int timeoutMs)\n      throws TimeoutException, InterruptedException {\n    long start = System.currentTimeMillis();\n    long duration = 10;\n    while (System.currentTimeMillis() - start < timeoutMs) {\n      try {\n        new Socket(host, port).close();\n        return;\n      } catch (IOException exn) {\n        Thread.sleep(duration);\n        duration = (long) (duration * 1.2);\n      }\n    }\n    throw new TimeoutException(\n        \"Timeout waiting for Python service startup after \"\n            + (System.currentTimeMillis() - start)\n            + \" milliseconds.\");\n  }\n}\n","sourceCodeStart":174,"sourceCodeEnd":198,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/python/src/main/java/org/apache/beam/sdk/extensions/python/PythonService.java#L174-L198","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nPythonService.waitForPort(\"localhost\", 5000, Duration.standardSeconds(30));\n// after\nPythonService.waitForPort(\"localhost\", 5000, Duration.standardMinutes(5));","handlingStrategy":"retry","validationCode":"try (var s = new java.net.Socket()) {\n  s.connect(new java.net.InetSocketAddress(host, port), 2000); // probe before expanding\n} catch (IOException e) { /* service not up yet: increase timeout or check logs */ }","typeGuard":null,"tryCatchPattern":"try {\n  PythonService.waitForPort(host, port, timeout);\n} catch (TimeoutException e) {\n  // inspect service logs, verify address, optionally retry with a longer timeout\n}","preventionTips":["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)"],"tags":["java","python","timeout","expansion-service","network"],"backgroundTag":"request-timeout","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}