apache/beam · error · TypeError

Proxy '{proxy}' has unsupported type '{type(proxy)}'

Error message

Proxy '{proxy}' has unsupported type '{type(proxy)}'

What it means

_element_typehint_from_proxy converts a proxy (a small pandas Series/DataFrame/Index standing in for a batch) into a Beam type hint. If the proxy is neither a Series (with .dtype) nor a recognized index type, it raises TypeError since no element type can be derived.

Source

Thrown at sdks/python/apache_beam/dataframe/schemas.py:130

  PCollection.
  """
  return element_typehint_from_dataframe_proxy(proxy, include_indexes).user_type


def _element_typehint_from_proxy(
    proxy: pd.core.generic.NDFrame, include_indexes: bool = False):
  if isinstance(proxy, pd.DataFrame):
    return element_typehint_from_dataframe_proxy(
        proxy, include_indexes=include_indexes)
  elif isinstance(proxy, pd.Series):
    if include_indexes:
      warnings.warn(
          "include_indexes=True for a Series input. Note that this "
          "parameter is _not_ respected for DeferredSeries "
          "conversion.")
    return dtype_to_fieldtype(proxy.dtype)
  else:
    raise TypeError(f"Proxy '{proxy}' has unsupported type '{type(proxy)}'")


def element_typehint_from_dataframe_proxy(
    proxy: pd.DataFrame, include_indexes: bool = False) -> RowTypeConstraint:

  output_columns = []
  if include_indexes:
    remaining_index_names = list(proxy.index.names)
    i = 0
    while len(remaining_index_names):
      index_name = remaining_index_names.pop(0)
      if index_name is None:
        raise ValueError(
            "Encountered an unnamed index. Cannot convert to a "
            "schema-aware PCollection with include_indexes=True. "
            "Please name all indexes or consider not including "
            "indexes.")
      elif index_name in remaining_index_names:

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure the transform returns a pandas DataFrame or Series (the proxy type must be one of these)
2. Wrap scalar results in a single-row/one-column DataFrame or Series before returning
3. Check the transform's return type annotation matches the actual proxy type produced
4. Inspect the proxy at type(proxy) printed in the message to find what object leaked through

Example fix

// before
def fn(df):
  return df['a'].sum()  # scalar proxy -> TypeError
// after
def fn(df):
  return df[['a']].sum()  # DataFrame proxy

import pandas as pd
if not isinstance(proxy, (pd.DataFrame, pd.Series, pd.Index)):
    raise TypeError(f'Transform proxy must be DataFrame/Series/Index, got {type(proxy)!r}')

import pandas as pd
def is_valid_proxy(proxy) -> bool:
    return isinstance(proxy, (pd.DataFrame, pd.Series, pd.Index))

try:
    output_type = schemas.element_typehint_from_dataframe_proxy(proxy)
except TypeError as e:
    raise TypeError(f'Bad proxy {type(proxy)!r}: wrap scalars in a DataFrame/Series') from e

When it happens

Trigger: Returning or producing, from a Beam DataFrame transform, a proxy object that is not a DataFrame/Series/Index — e.g. a scalar, dict, or custom object; incorrect return type from a dofn/apply over dataframes.

Common situations: Custom transforms in beam.dataframe.apply that accidentally return a plain value or a non-pandas object instead of a DataFrame/Series; version differences changing proxy wrapper classes.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Encountered unknown type {other!r}
• Proxy '{proxy}' has unsupported type '{type(proxy)}'
• Unable to convert objects of type %s to a PCollection
• Cannot specify both 'labels' and 'index'/'columns'
• axis must be one of (0, 1, 'index', 'columns'), got '%s'

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