{"record":{"id":"c8c7f18b916a77c8","repo":"apache/beam","slug":"error-starting-worker-s","errorCode":null,"errorMessage":"Error starting worker: %s","messagePattern":"Error starting worker: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/runners/portability/fn_api_runner/worker_handlers.py","lineNumber":643,"sourceCode":"  def start_worker(self):\n    # type: () -> None\n    _LOGGER.info(\"Requesting worker at %s\", self._external_payload.endpoint.url)\n    stub = beam_fn_api_pb2_grpc.BeamFnExternalWorkerPoolStub(\n        GRPCChannelFactory.insecure_channel(\n            self._external_payload.endpoint.url))\n    _LOGGER.info('self.control_address: %s' % self.control_address)\n    control_descriptor = endpoints_pb2.ApiServiceDescriptor(\n        url=self.control_address)\n    response = stub.StartWorker(\n        beam_fn_api_pb2.StartWorkerRequest(\n            worker_id=self.worker_id,\n            control_endpoint=control_descriptor,\n            artifact_endpoint=control_descriptor,\n            provision_endpoint=control_descriptor,\n            logging_endpoint=self.logging_api_service_descriptor(),\n            params=self._external_payload.params))\n    if response.error:\n      raise RuntimeError(\"Error starting worker: %s\" % response.error)\n\n  def stop_worker(self):\n    # type: () -> None\n    pass\n\n  def host_from_worker(self):\n    # type: () -> str\n    # TODO(https://github.com/apache/beam/issues/19947): Reconcile across\n    # platforms.\n    if sys.platform in ['win32', 'darwin']:\n      return 'localhost'\n    import socket\n    return socket.getfqdn()\n\n\n@WorkerHandler.register_environment(python_urns.EMBEDDED_PYTHON_GRPC, bytes)\nclass EmbeddedGrpcWorkerHandler(GrpcWorkerHandler):\n  def __init__(","sourceCodeStart":625,"sourceCodeEnd":661,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/runners/portability/fn_api_runner/worker_handlers.py#L625-L661","documentation":"Raised by the Embedded/external worker handler after sending a ProvisionInfo request to an externally managed (Docker-based) SDK harness: the harness responded with a non-empty error field, meaning it failed to start itself. The runner surfaces the harness's own error text verbatim via RuntimeError.","triggerScenarios":"Calling start_worker on an external worker handler whose container started but the harness process inside replied with error to the provision request — e.g. bad pipeline options, missing dependencies in the container, or wrong endpoints.","commonSituations":"Docker image lacking required Python packages; container cannot reach the control/logging endpoints (wrong docker network); incompatible harness image version; invalid environment passed via provision payload.","solutions":["Read the %s payload in the message — it contains the harness's own failure reason and fix that underlying issue.","Verify the container can reach the runner's control/logging endpoints (shared docker network, correct host binding).","Pin --sdk_harness_container_image_overrides to an image matching the runner's Beam version.","Check container logs (docker logs <container>) for startup/dependency errors."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if response and getattr(response, 'error', None):\n    precheck_failed = True","typeGuard":null,"tryCatchPattern":"try:\n    handler.start_worker()\nexcept RuntimeError as e:\n    log.error('harness provision failed: %s', e)\n    inspect_container_logs()","preventionTips":["Use the same docker network for runner and containers","Verify endpoint reachability before start","Pin harness image versions"],"tags":["docker","worker-lifecycle","grpc","startup"],"backgroundTag":"worker-startup-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}