apache/beam · error · ValueError

Invalid device value: {device}. Please specify either CPU or

Error message

Invalid device value: {device}. Please specify either CPU or GPU. Defaults to GPU if no value is provided.

What it means

HuggingFacePipelineModelHandler accepts only 'CPU' or 'GPU' (case-insensitive) for its device parameter. Any other value raises ValueError in _deduplicate_device_value, which normalizes the device into load_pipeline_args.

Source

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

        batch_bucket_boundaries=batch_bucket_boundaries,
        large_model=large_model,
        model_copies=model_copies,
        **kwargs)
    self._task = task
    self._model = model
    self._inference_fn = inference_fn
    self._load_pipeline_args = load_pipeline_args if load_pipeline_args else {}
    self._framework = "pt"

    # Check if the device is specified twice. If true then the device parameter
    # of model handler is overridden.
    self._deduplicate_device_value(device)
    _validate_constructor_args_hf_pipeline(self._task, self._model)

  def _deduplicate_device_value(self, device: Optional[str]):
    current_device = device.upper() if device else None
    if (current_device and current_device != 'CPU' and current_device != 'GPU'):
      raise ValueError(
          f"Invalid device value: {device}. Please specify "
          "either CPU or GPU. Defaults to GPU if no value "
          "is provided.")
    if 'device' not in self._load_pipeline_args:
      if current_device == 'CPU':
        self._load_pipeline_args['device'] = 'cpu'
      else:
        if is_gpu_available_torch():
          self._load_pipeline_args['device'] = 'cuda:0'
        else:
          _LOGGER.warning(
              "HuggingFaceModelHandler specified a 'GPU' device, "
              "but GPUs are not available. Switching to CPU.")
          self._load_pipeline_args['device'] = 'cpu'
    else:
      if current_device:
        raise ValueError(
            '`device` specified in `load_pipeline_args`. `device` '

View on GitHub (pinned to 12126d8942)

Solutions

1. Use device='GPU' instead of 'cuda'/'cuda:0'.
2. Use device='CPU' or omit device (defaults to GPU).
3. Normalize the value before passing: device = 'GPU' if 'cuda' in raw_device else 'CPU'.

Example fix

// before
handler = HuggingFacePipelineModelHandler(task='translation', device='cuda:0')
// after
handler = HuggingFacePipelineModelHandler(task='translation', device='GPU')

if device and device.upper() not in ('CPU', 'GPU'):
    raise ValueError(f'device must be CPU or GPU, got {device}')

def valid_device(device) -> bool:
    return device is None or str(device).upper() in ('CPU', 'GPU')

try:
    handler = HuggingFacePipelineModelHandler(task=task, device=device)
except ValueError as e:
    if 'Invalid device value' in str(e):
        device = 'GPU' if torch.cuda.is_available() else 'CPU'
        handler = HuggingFacePipelineModelHandler(task=task, device=device)
    else:
        raise

When it happens

Trigger: HuggingFacePipelineModelHandler(device='cuda') or device='tpu' or device='gpu:0'.

Common situations: PyTorch-style device strings ('cuda', 'cuda:0') carried over from other handlers; typos like 'gpu ' or 'Cpu ' variants with trailing spaces.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Please provide both model class and model uri to load the mo
• Please provide either task or model to the HuggingFacePipeli
• `device` specified in `load_pipeline_args`. `device` paramet
• sentence-transformers is required to use HuggingfaceTextEmbe
• sentence-transformers is required to use HuggingfaceImageEmb

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