{"record":{"id":"e5168e8851e35ed4","repo":"apache/beam","slug":"transform-service-did-not-start-in-timeout-1000-seconds","errorCode":null,"errorMessage":"Transform Service did not start in {timeout / 1000} seconds.","messagePattern":"Transform Service did not start in (.+?) seconds\\.","errorType":"exception","errorClass":"TimeoutException","httpStatus":null,"severity":"error","filePath":"sdks/java/transform-service/launcher/src/main/java/org/apache/beam/sdk/transformservice/launcher/TransformServiceLauncher.java","lineNumber":316,"sourceCode":"    while (System.currentTimeMillis() - startTime < timeout) {\n      String statusFileName = getStatus();\n      try {\n        // We are just waiting for a local process. No need for exponential backoff.\n        this.wait(1000);\n      } catch (InterruptedException e) {\n        // Ignore and retry.\n      }\n\n      String output = String.join(\" \", java.nio.file.Files.readAllLines(Paths.get(statusFileName)));\n      if (!output.isEmpty()) {\n        if (output.contains(\"transform-service\")) {\n          // Transform service was started since we found matching logs.\n          return;\n        }\n      }\n    }\n\n    throw new TimeoutException(\n        \"Transform Service did not start in \" + timeout / 1000 + \" seconds.\");\n  }\n\n  private synchronized String getStatus() throws IOException {\n    File outputOverride = File.createTempFile(\"output_override\", null);\n    outputOverride.deleteOnExit();\n    runDockerComposeCommand(ImmutableList.of(\"ps\"), outputOverride);\n\n    return outputOverride.getAbsolutePath();\n  }\n\n  private static class ArgConfig {\n\n    static final String PROJECT_NAME_ARG_NAME = \"project_name\";\n    static final String COMMAND_ARG_NAME = \"command\";\n    static final String PORT_ARG_NAME = \"port\";\n    static final String BEAM_VERSION_ARG_NAME = \"beam_version\";\n","sourceCodeStart":298,"sourceCodeEnd":334,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/transform-service/launcher/src/main/java/org/apache/beam/sdk/transformservice/launcher/TransformServiceLauncher.java#L298-L334","documentation":"waitTillUp polls the transform service logs (via docker compose / container status) until it sees startup-completion markers. If no matching logs appear within the given timeout, it throws this TimeoutException. It means the container was launched but never signaled readiness within the allotted window.","triggerScenarios":"Calling waitTillUp (directly or via expand/upgradeTransformsViaTransformService/main with command \"up\") when the service containers fail to reach the ready log line before timeout: image pull failures, port conflicts, slow image pulls on first run, or the service crashing during startup. Note waitTillUp(-1) passes a negative/very large timeout.","commonSituations":"First-time start pulling a large Beam SDK transform-service image over a slow network; Docker daemon misconfiguration; the configured port already in use causing the service to exit; insufficient memory in the container environment.","solutions":["Check container logs (docker compose logs / service status) for the actual startup failure (image pull error, port conflict, crash).","Increase the startup timeout argument to waitTillUp to accommodate slow image pulls.","Verify Docker/Docker Compose is installed, running, and the configured port is free before starting.","Retry the \"up\" command after fixing the underlying container failure."],"exampleFix":"// before\nservice.waitTillUp(30_000); // too short for first image pull\n\n// after\nservice.waitTillUp(300_000); // allow 5 minutes for image download","handlingStrategy":"try-catch","validationCode":"// pre-check environment before calling waitTillUp\nProcess p = new ProcessBuilder(\"docker\", \"info\").inheritIO().start();\nif (p.waitFor() != 0) throw new IllegalStateException(\"Docker daemon not reachable\");","typeGuard":null,"tryCatchPattern":"try {\n  service.waitTillUp(timeoutMs);\n} catch (java.util.concurrent.TimeoutException e) {\n  LOG.error(\"Transform service not ready: {}. Check container logs (docker compose logs)\", e.getMessage());\n  service.shutdown(); // clean up partial start\n  throw e;\n}","preventionTips":["Pre-pull the transform-service image before first launch to avoid slow startup.","Use generous timeouts (minutes, not seconds) for the first run.","Ensure the configured port is free before starting."],"tags":["java","timeout","docker","service-startup"],"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"}