apache/beam · error · ValueError

Transform service did not start in %s seconds.

Error message

Transform service did not start in %s seconds.

What it means

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.

Source

Thrown at sdks/python/apache_beam/utils/transform_service_launcher.py:219

  def status(self):
    with self._launcher_lock:
      self._run_docker_compose_command(['ps'])

  def wait_till_up(self, timeout_ms):
    channel = self._get_channel()

    timeout_ms = (
        TransformServiceLauncher._DEFAULT_START_WAIT_TIMEOUT
        if timeout_ms <= 0 else timeout_ms)

    # Waiting till the service is up.
    channel_ready = grpc.channel_ready_future(channel)
    wait_secs = .1
    start_time = time.time()
    while True:
      if (time.time() - start_time) * 1000 > timeout_ms > 0:
        raise ValueError(
            'Transform service did not start in %s seconds.' %
            (timeout_ms / 1000))
      try:
        channel_ready.result(timeout=wait_secs)
        break
      except (grpc.FutureTimeoutError, grpc.RpcError):
        wait_secs *= 1.2
        logging.log(
            logging.WARNING if wait_secs > 1 else logging.DEBUG,
            'Waiting for the transform service to be ready at %s.',
            self._address)

    logging.info('Transform service ' + self._project_name + ' started.')

  def _get_status(self):
    tmp = tempfile.NamedTemporaryFile(delete=False)
    self._run_docker_compose_command(['ps'], tmp)
    tmp.close()

View on GitHub (pinned to 12126d8942)

Solutions

1. Increase the timeout: pass a larger timeout_ms to wait_till_up / the launcher constructor.
2. Check the launcher's subprocess logs for startup failures (missing jar, port already in use, bad service address).
3. Verify the service address/port is correct and free: confirm nothing else is bound to the port and the service config matches.
4. Retry startup, or run `beam_transform_service ps`/status to inspect the launcher state.
5. Catch ValueError around wait_till_up/context entry and fail gracefully with cleanup (shutdown()).

Example fix

// before
with TransformServiceLauncher(address, port, timeout_ms=30000) as service:
    ...
// after
with TransformServiceLauncher(address, port, timeout_ms=300000) as service:
    ...

sock = socket.socket()
try:
    sock.connect((host, port))
    reachable = True
except OSError:
    reachable = False
finally:
    sock.close()

try:
    launcher.wait_till_up(timeout_ms)
except ValueError as e:
    launcher.shutdown()
    raise RuntimeError(f'transform service failed to start: {e}') from e

When it happens

Trigger: 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.

Common situations: 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.

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.

Related errors

• PubSub publish timeout exceeded {self.FLUSH_TIMEOUT_SECS} se
• Timeout {timeout} exceeded while completing request: {reques
• Timeout waiting to acquire model: {tag} after {wait_time_ela
• input is already set.
• Buffer size {size} exceeds GRPC limit {_FLUSH_MAX_SIZE}. Thi

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