{"record":{"id":"467b1d4a92ab3dfc","repo":"apache/beam","slug":"keyedmodelhandler-cannot-map-records-to-multiple-models-if","errorCode":null,"errorMessage":"KeyedModelHandler cannot map records to multiple models if one or more of its ModelHandlers require multiple model copies (set via model_copies). To fix, verify that each ModelHandler is not set to load multiple copies of its model.","messagePattern":"KeyedModelHandler cannot map records to multiple models if one or more of its ModelHandlers require multiple model copies \\(set via model_copies\\)\\. To fix, verify that each ModelHandler is not set to load multiple copies of its model\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/ml/inference/base.py","lineNumber":1035,"sourceCode":"    if self._single_model:\n      return self._unkeyed.update_model_path(model_path=model_path)\n    if model_path is not None:\n      raise RuntimeError(\n          'Model updates are currently not supported for ' +\n          'KeyedModelHandlers with multiple different per-key ' +\n          'ModelHandlers.')\n\n  def share_model_across_processes(self) -> bool:\n    if self._single_model:\n      return self._unkeyed.share_model_across_processes()\n    return True\n\n  def model_copies(self) -> int:\n    if self._single_model:\n      return self._unkeyed.model_copies()\n    for mh in self._id_to_mh_map.values():\n      if mh.model_copies() != 1:\n        raise ValueError(\n            'KeyedModelHandler cannot map records to multiple '\n            'models if one or more of its ModelHandlers '\n            'require multiple model copies (set via '\n            'model_copies). To fix, verify that each '\n            'ModelHandler is not set to load multiple copies of '\n            'its model.')\n\n    return 1\n\n  def override_metrics(self, metrics_namespace: str = '') -> bool:\n    if self._single_model:\n      return self._unkeyed.override_metrics(metrics_namespace)\n\n    self._metrics_namespace = metrics_namespace\n    self._default_metrics_collector = _MetricsCollector(metrics_namespace)\n    for cohort_id in self._id_to_mh_map:\n      self._metrics_collectors[cohort_id] = _MetricsCollector(\n          metrics_namespace, f'{cohort_id}-')","sourceCodeStart":1017,"sourceCodeEnd":1053,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/ml/inference/base.py#L1017-L1053","documentation":"Raised by KeyedModelHandler.model_copies when any of its per-key ModelHandlers requests multiple copies of its model. Multi-copy loading is incompatible with keyed handlers that route records to multiple models, because key-to-model mapping assumes one copy per handler.","triggerScenarios":"Calling model_copies() on a multi-model KeyedModelHandler where at least one inner ModelHandler was configured with model_copies > 1 (e.g. handler.load_model_args or set_model_copies(2)).","commonSituations":"Optimizing GPU memory by duplicating models via model_copies, then wrapping those handlers in a KeyedModelHandler; copy-pasting single-handler multi-copy config into per-key handlers.","solutions":["Set model_copies back to 1 on every inner ModelHandler.","If multiple copies are needed, use separate handlers/pipelines rather than a multi-model KeyedModelHandler.","Assert each inner handler's model_copies() == 1 before wrapping in KeyedModelHandler."],"exampleFix":"// before\nmh = TritonModelHandler(...)\nmh.set_model_copies(2)\nkeyed = KeyedModelHandler({'k1': mh, 'k2': mh2})\n// after\nmh = TritonModelHandler(...)\nmh.set_model_copies(1)\nkeyed = KeyedModelHandler({'k1': mh, 'k2': mh2})","handlingStrategy":"validation","validationCode":"if any(mh.model_copies() != 1 for mh in inner_handlers.values()):\n    raise ValueError('model_copies > 1 unsupported in multi-model KeyedModelHandler')","typeGuard":"def single_copy(mh) -> bool:\n    return mh.model_copies() == 1","tryCatchPattern":null,"preventionTips":["Keep model_copies at the default (1) when wrapping handlers in KeyedModelHandler.","Document that multi-copy loading and keyed multi-model routing are mutually exclusive."],"tags":["python","apache-beam","ml-inference","incompatible-options"],"backgroundTag":"conflicting-config-options","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"}