apache/beam · error · RuntimeError

Please provide both model class and model uri to load the mo

Error message

Please provide both model class and model uri to load the model.Got params as model_uri={model_uri} and model_class={model_class}.

What it means

HuggingFaceModelHandler's constructor validation raises RuntimeError when neither model_uri nor model_class is provided. Both are required together to load a model from a state dict (the message template is shared by all three branches of _validate_constructor_args, so it fires even though the message says 'both'). This branch handles the case where BOTH are missing.

Source

Thrown at sdks/python/apache_beam/ml/inference/huggingface_inference.py:121

  TokenClassification = 'token-classification'
  Translation = 'translation'
  VideoClassification = 'video-classification'
  VisualQuestionAnswering = 'visual-question-answering'
  VQA = 'vqa'
  ZeroShotAudioClassification = 'zero-shot-audio-classification'
  ZeroShotClassification = 'zero-shot-classification'
  ZeroShotImageClassification = 'zero-shot-image-classification'
  ZeroShotObjectDetection = 'zero-shot-object-detection'
  Translation_XX_to_YY = 'translation_XX_to_YY'


def _validate_constructor_args(model_uri, model_class):
  message = (
      "Please provide both model class and model uri to load the model."
      "Got params as model_uri={model_uri} and "
      "model_class={model_class}.")
  if not model_uri and not model_class:
    raise RuntimeError(
        message.format(model_uri=model_uri, model_class=model_class))
  elif not model_uri:
    raise RuntimeError(
        message.format(model_uri=model_uri, model_class=model_class))
  elif not model_class:
    raise RuntimeError(
        message.format(model_uri=model_uri, model_class=model_class))


def no_gpu_available_warning():
  _LOGGER.warning(
      "HuggingFaceModelHandler specified a 'GPU' device, "
      "but GPUs are not available. Switching to CPU.")


def is_gpu_available_torch():
  if torch.cuda.is_available():
    return True

View on GitHub (pinned to 12126d8942)

Solutions

Pass both model_uri (path/URI of the state dict) and model_class (the transformers model class).
If loading a pipeline instead, use HuggingFacePipelineModelHandler with task or model.
Check that config/env values for model_uri and model_class are not empty/None at call time.

Example fix

// before
handler = HuggingFaceModelHandler(load_pipeline_args={'device': 'cpu'})
// after
handler = HuggingFaceModelHandler(model_uri='gs://bucket/model.pth', model_class=AutoModelForSequenceClassification)

Defensive patterns

Strategy: validation

Validate before calling

def can_construct(model_uri, model_class):
    return bool(model_uri) and bool(model_class)
if not can_construct(uri, cls):
    raise ValueError('HuggingFaceModelHandler needs both model_uri and model_class')

Type guard

def has_model_params(uri, cls) -> bool:
    return isinstance(uri, str) and uri != '' and cls is not None

Try / catch

try:
    handler = HuggingFaceModelHandler(model_uri=uri, model_class=cls)
except RuntimeError as e:
    if 'model_uri' in str(e) or 'model_class' in str(e):
        handler = HuggingFacePipelineModelHandler(task=task)
    else:
        raise

Prevention

Validate both params at config-load time, before building the pipeline
Never pass model_uri/model_class from unchecked env vars
Prefer HuggingFacePipelineModelHandler when you only have a model id

When it happens

Trigger: Calling HuggingFaceModelHandler() with no model_uri and no model_class; __init__ calls _validate_constructor_args which hits the first 'if not model_uri and not model_class' branch.

Common situations: Constructing the handler with only task/load_pipeline_args; copying example code and dropping the model-loading params; refactoring away the two coupled params.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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