apache/beam · error · RuntimeError

SDK failed to start. Final status is

Error message

SDK failed to start. Final status is %s

What it means

The Docker-based worker handler polls the container's status while waiting for the SDK harness to become ready. If the container reports 'dead' or 'exited' before the ready handshake completes, the runner dumps container logs and raises this RuntimeError, since the SDK harness never started.

Solutions

  1. Inspect the docker container logs printed just before the error for the actual crash cause.
  2. Rebuild/pull a correct, version-matched SDK harness image (docker pull the image for your Beam version).
  3. Increase container memory/CPU limits (e.g. --docker_container_run_options '--memory=4g').
  4. Verify the image's entrypoint launches the apache_beam worker main; check --sdk_harness_container_image_overrides settings.
Defensive patterns

Strategy: try-catch

Validate before calling

subprocess.call(['docker', 'inspect', '-f', '{{.State.Status}}', container_id])

Try / catch

try:
    handler.start_worker()
except RuntimeError as e:
    subprocess.call(['docker', 'container', 'logs', container_id])
    raise

Prevention

When it happens

Trigger: start_worker watching a docker container that terminates during startup: image crash, OOM kill, bad entrypoint, missing python/beam package, or the harness process exiting on a config error before registering with the runner.

Common situations: Corrupt or wrong-architecture container image; container killed by memory limits; harness crashes on import errors from user code baked into the image; docker daemon resource exhaustion.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/runners/portability/fn_api_runner/worker_handlers.py:822

      ]).strip()
      assert self._container_id is not None
      while True:
        status = subprocess.check_output([
            'docker', 'inspect', '-f', '{{.State.Status}}', self._container_id
        ]).strip()
        _LOGGER.info(
            'Waiting for docker to start up. Current status is %s' %
            status.decode('utf-8'))
        if status == b'running':
          _LOGGER.info(
              'Docker container is running. container_id = %s, '
              'worker_id = %s',
              self._container_id,
              self.worker_id)
          break
        elif status in (b'dead', b'exited'):
          subprocess.call(['docker', 'container', 'logs', self._container_id])
          raise RuntimeError(
              'SDK failed to start. Final status is %s' %
              status.decode('utf-8'))
      time.sleep(1)
    self._done = False
    t = threading.Thread(target=self.watch_container)
    t.daemon = True
    t.start()

  def watch_container(self):
    # type: () -> None
    while not self._done:
      assert self._container_id is not None
      status = subprocess.check_output(
          ['docker', 'inspect', '-f', '{{.State.Status}}',
           self._container_id]).strip()
      if status != b'running':
        if not self._done:
          logs = subprocess.check_output([

View on GitHub (pinned to 12126d8942)