{"record":{"id":"47de688e2290dee6","repo":"apache/beam","slug":"transform-service-did-not-start-in-s-seconds","errorCode":null,"errorMessage":"Transform service did not start in %s seconds.","messagePattern":"Transform service did not start in (.+?) seconds\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/utils/transform_service_launcher.py","lineNumber":219,"sourceCode":"\n  def status(self):\n    with self._launcher_lock:\n      self._run_docker_compose_command(['ps'])\n\n  def wait_till_up(self, timeout_ms):\n    channel = self._get_channel()\n\n    timeout_ms = (\n        TransformServiceLauncher._DEFAULT_START_WAIT_TIMEOUT\n        if timeout_ms <= 0 else timeout_ms)\n\n    # Waiting till the service is up.\n    channel_ready = grpc.channel_ready_future(channel)\n    wait_secs = .1\n    start_time = time.time()\n    while True:\n      if (time.time() - start_time) * 1000 > timeout_ms > 0:\n        raise ValueError(\n            'Transform service did not start in %s seconds.' %\n            (timeout_ms / 1000))\n      try:\n        channel_ready.result(timeout=wait_secs)\n        break\n      except (grpc.FutureTimeoutError, grpc.RpcError):\n        wait_secs *= 1.2\n        logging.log(\n            logging.WARNING if wait_secs > 1 else logging.DEBUG,\n            'Waiting for the transform service to be ready at %s.',\n            self._address)\n\n    logging.info('Transform service ' + self._project_name + ' started.')\n\n  def _get_status(self):\n    tmp = tempfile.NamedTemporaryFile(delete=False)\n    self._run_docker_compose_command(['ps'], tmp)\n    tmp.close()","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/utils/transform_service_launcher.py#L201-L237","documentation":"TransformServiceLauncher.wait_till_up() polls a gRPC channel for the transform service to become reachable. If the channel is not ready before timeout_ms elapses, it raises ValueError reporting the configured timeout in seconds, meaning the service either failed to start or is not listening on the expected port.","triggerScenarios":"Calling wait_till_up(timeout_ms) (also via the launcher's __enter__ context manager or `beam_transform_service up` CLI) when the subprocess fails to launch, binds a different port, or the gRPC channel never becomes ready within timeout_ms.","commonSituations":"Starting the Beam transform service for SqlTransform/externals in notebooks or tests where the jar/docker image is missing or slow to boot; port conflicts or firewall blocking localhost gRPC; too-short timeout on slow machines/containers.","solutions":["Increase the timeout: pass a larger timeout_ms to wait_till_up / the launcher constructor.","Check the launcher's subprocess logs for startup failures (missing jar, port already in use, bad service address).","Verify the service address/port is correct and free: confirm nothing else is bound to the port and the service config matches.","Retry startup, or run `beam_transform_service ps`/status to inspect the launcher state.","Catch ValueError around wait_till_up/context entry and fail gracefully with cleanup (shutdown())."],"exampleFix":"// before\nwith TransformServiceLauncher(address, port, timeout_ms=30000) as service:\n    ...\n// after\nwith TransformServiceLauncher(address, port, timeout_ms=300000) as service:\n    ...","handlingStrategy":"retry","validationCode":"sock = socket.socket()\ntry:\n    sock.connect((host, port))\n    reachable = True\nexcept OSError:\n    reachable = False\nfinally:\n    sock.close()","typeGuard":null,"tryCatchPattern":"try:\n    launcher.wait_till_up(timeout_ms)\nexcept ValueError as e:\n    launcher.shutdown()\n    raise RuntimeError(f'transform service failed to start: {e}') from e","preventionTips":["Allocate generous timeouts for container/jvm-based services on slow hosts.","Capture and inspect the launcher's subprocess logs when startup fails.","Check the port is free and the address is reachable before starting.","Retry startup once before failing the pipeline."],"tags":["python","apache-beam","grpc","service-startup","timeout"],"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"}