{"record":{"id":"08d2555d33b9bdd5","repo":"apache/beam","slug":"pickling-error-encountered-while-running-inference-this-may","errorCode":null,"errorMessage":"Pickling error encountered while running inference. This may be caused by trying to send unpickleable data to a model which is shared across processes. For more information, see https://beam.apache.org/documentation/ml/large-language-modeling/#pickling-errors","messagePattern":"Pickling error encountered while running inference\\. This may be caused by trying to send unpickleable data to a model which is shared across processes\\. For more information, see https://beam\\.apache\\.org/documentation/ml/large-language-modeling/#pickling-errors","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/ml/inference/base.py","lineNumber":2112,"sourceCode":"      model = self._model.next_model()\n      if isinstance(model, str):\n        # ModelManager with MultiProcessShared returns the model tag\n        unique_tag = model\n        model = multi_process_shared.MultiProcessShared(\n            lambda: None, tag=model, always_proxy=True).acquire()\n      try:\n        result_generator = (OOMProtectedFn(self._model_handler.run_inference))(\n            batch, model, inference_args)\n      finally:\n        # Always release the model so that it can be reloaded.\n        if self.use_model_manager:\n          self._model.release_model(self._model_tag, unique_tag)\n    except BaseException as e:\n      if self._metrics_collector:\n        self._metrics_collector.failed_batches_counter.inc()\n      if (e is pickle.PickleError and\n          self._model_handler.share_model_across_processes()):\n        raise TypeError(\n            'Pickling error encountered while running inference. '\n            'This may be caused by trying to send unpickleable '\n            'data to a model which is shared across processes. '\n            'For more information, see '\n            'https://beam.apache.org/documentation/ml/large-language-modeling/#pickling-errors'  # pylint: disable=line-too-long\n        ) from e\n      raise e\n    predictions = list(result_generator)\n\n    end_time = _to_microseconds(self._clock.time_ns())\n    inference_latency = end_time - start_time\n    num_bytes = self._model_handler.get_num_bytes(batch)\n    num_elements = len(batch)\n    if self._metrics_collector:\n      self._metrics_collector.update(num_elements, num_bytes, inference_latency)\n\n    return predictions\n","sourceCodeStart":2094,"sourceCodeEnd":2130,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/ml/inference/base.py#L2094-L2130","documentation":"Raised when a pickle.PickleError occurs during RunInference on a model configured with share_model_across_processes. Sharing a model across processes requires data sent to the model to be picklable; unpickleable data (locks, open handles, lambdas, etc.) breaks serialization and is re-raised as this TypeError with a link to Beam's pickling-error docs.","triggerScenarios":"Running inference on a model handler with share_model_across_processes() enabled while the batch contains objects that cannot be pickled (e.g. file handles, threads, local lambdas, C-extension objects).","commonSituations":"Passing custom non-picklable objects as model input; large-language-model pipelines with shared models on multi-worker runners; lambda functions defined in __main__ used in preprocessing outputs.","solutions":["Make all data sent to the model picklable (replace lambdas with top-level functions, remove open handles/locks).","Disable share_model_across_processes() if sharing is not required, so each process loads its own model.","Use dill-based serialization or convert custom objects to plain picklable types (dicts, bytes) before inference."],"exampleFix":"// before\nclass Ctx:\n  def __init__(self): self.fh = open('data.bin')  # unpickleable\nrows = p | RunInference(handler.share_model_across_processes()) with Ctx() inputs\n// after\nrows = p | Map(lambda x: (x, read_bytes('data.bin'))) | RunInference(handler)  # pass picklable data, don't share model","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    result = beam.RunInference(handler.share_model_across_processes())\nexcept TypeError as e:\n    if 'Pickling error' in str(e):\n        logging.error('Unpickleable data with shared model: %s', e.__cause__)\n        raise\ncatch (e) { if (String(e).includes('Pickling error')) { /* fix data picklability or unshare model */ } }","preventionTips":["Prefer top-level functions over lambdas in data flowing to shared models.","Ensure model inputs contain only picklable types (str, bytes, dict, list).","Only enable share_model_across_processes when data is known picklable."],"tags":["python","apache-beam","pickling","ml-inference"],"backgroundTag":"json-marshal-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"}