apache/beam · error · TypeCheckError

PTransform cannot have both positional and keyword input…

Error message

PTransform cannot have both positional and keyword input type hints without overriding %s._type_check_%s()

What it means

Beam's type-hint checking supports either positional arg hints or keyword hints, not both for inputs (keywords only allowed for outputs, used as tagged output types). Combining both without overriding the transform's _type_check_inputs/_type_check_outputs raises TypeCheckError.

Solutions

  1. Use only positional input type hints, or only keyword hints if the framework allows for your transform.
  2. Override _type_check_inputs (or _type_check_outputs) in your PTransform subclass to implement custom checking.
  3. Move complex hint logic into a custom typecheck override rather than mixing hint styles.

Example fix

// before
class MyT(beam.PTransform):
  ...
MyT().with_type_input_types(int, **{'b': str})  # mixed
// after
class MyT(beam.PTransform):
  def _type_check_inputs(self, pvalueish, hints): ...
  def _type_check_outputs(self, pvalueish, hints): ...
Defensive patterns

Strategy: type-guard

Validate before calling

arg_hints, kwarg_hints = hints
assert not (arg_hints and kwarg_hints), "use positional OR keyword hints, not both"

Try / catch

try:
  t.with_input_types(*args, **kwargs)
except TypeCheckError:
  t = MyTransform().with_input_types(*args)  # drop kwargs, override _type_check_inputs instead

Prevention

When it happens

Trigger: Decorating or calling with_type_hint on a PTransform with both *args hints and **kwargs hints on the input side (e.g. @with_input_types(a=int, **{'b': str}) style mixing).

Common situations: Misusing with_input_types decorator with both positional and keyword specs; custom PTransforms adding hints for inputs that use keyword syntax.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/ptransform.py:499

  def type_check_inputs(self, pvalueish):
    self.type_check_inputs_or_outputs(pvalueish, 'input')

  def infer_output_type(self, unused_input_type):
    return self.get_type_hints().simple_output_type(self.label) or typehints.Any

  def type_check_outputs(self, pvalueish):
    self.type_check_inputs_or_outputs(pvalueish, 'output')

  def type_check_inputs_or_outputs(self, pvalueish, input_or_output):
    type_hints = self.get_type_hints()
    hints = getattr(type_hints, input_or_output + '_types')
    if hints is None or not any(hints):
      return
    arg_hints, kwarg_hints = hints
    # Output types can have kwargs for tagged output types.
    if arg_hints and kwarg_hints and input_or_output != 'output':
      raise TypeCheckError(
          'PTransform cannot have both positional and keyword input type hints'
          ' without overriding %s._type_check_%s()' %
          (self.__class__, input_or_output))
    root_hint = (
        arg_hints[0] if len(arg_hints) == 1 else arg_hints or kwarg_hints)
    for context, pvalue_, hint in _ZipPValues().visit(pvalueish, root_hint):
      if isinstance(pvalue_, DoOutputsTuple):
        continue
      if pvalue_.element_type is None:
        # TODO(robertwb): It's a bug that we ever get here. (typecheck)
        continue
      if hint and not typehints.is_consistent_with(pvalue_.element_type, hint):
        at_context = ' %s %s' % (input_or_output, context) if context else ''
        raise TypeCheckError(
            '{type} type hint violation at {label}{context}: expected {hint}, '
            'got {actual_type}'.format(
                type=input_or_output.title(),
                label=self.label,

View on GitHub (pinned to 12126d8942)