apache/beam · error · ValueError

KeyedModelHandler cannot map records to multiple models if…

Error message

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.

What it means

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.

Solutions

1. Set model_copies back to 1 on every inner ModelHandler.
2. If multiple copies are needed, use separate handlers/pipelines rather than a multi-model KeyedModelHandler.
3. Assert each inner handler's model_copies() == 1 before wrapping in KeyedModelHandler.

Example fix

// before
mh = TritonModelHandler(...)
mh.set_model_copies(2)
keyed = KeyedModelHandler({'k1': mh, 'k2': mh2})
// after
mh = TritonModelHandler(...)
mh.set_model_copies(1)
keyed = KeyedModelHandler({'k1': mh, 'k2': mh2})

if any(mh.model_copies() != 1 for mh in inner_handlers.values()):
    raise ValueError('model_copies > 1 unsupported in multi-model KeyedModelHandler')

def single_copy(mh) -> bool:
    return mh.model_copies() == 1

When it happens

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

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

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Cannot make make an unkeyed model handler with pre or…
• Cannot override RemoteModelHandler.load_model, implement…
• Cannot override RemoteModelHandler.run_inference, implement…
• Cannot use an unkeyed model handler with pre or…
• Empty list maps to model handler

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

Appendix: source

Thrown at sdks/python/apache_beam/ml/inference/base.py:1035

    if self._single_model:
      return self._unkeyed.update_model_path(model_path=model_path)
    if model_path is not None:
      raise RuntimeError(
          'Model updates are currently not supported for ' +
          'KeyedModelHandlers with multiple different per-key ' +
          'ModelHandlers.')

  def share_model_across_processes(self) -> bool:
    if self._single_model:
      return self._unkeyed.share_model_across_processes()
    return True

  def model_copies(self) -> int:
    if self._single_model:
      return self._unkeyed.model_copies()
    for mh in self._id_to_mh_map.values():
      if mh.model_copies() != 1:
        raise ValueError(
            '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.')

    return 1

  def override_metrics(self, metrics_namespace: str = '') -> bool:
    if self._single_model:
      return self._unkeyed.override_metrics(metrics_namespace)

    self._metrics_namespace = metrics_namespace
    self._default_metrics_collector = _MetricsCollector(metrics_namespace)
    for cohort_id in self._id_to_mh_map:
      self._metrics_collectors[cohort_id] = _MetricsCollector(
          metrics_namespace, f'{cohort_id}-')

View on GitHub (pinned to 12126d8942)