{"record":{"id":"43556d49a6381c6a","repo":"apache/beam","slug":"unable-to-convert-objects-of-type-s-to-a-pcollection","errorCode":null,"errorMessage":"Unable to convert objects of type %s to a PCollection","messagePattern":"Unable to convert objects of type (.+?) to a PCollection","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/dataframe/convert.py","lineNumber":234,"sourceCode":"    # of these variables in the calling context.\n    label = 'ToPCollection(%s)' % ', '.join(_var_name(e, 3) for e in dataframes)\n\n  # Support for non-deferred dataframes.\n  deferred_dataframes = []\n  for ix, df in enumerate(dataframes):\n    if isinstance(df, frame_base.DeferredBase):\n      # TODO(robertwb): Maybe extract pipeline object?\n      deferred_dataframes.append(df)\n    elif isinstance(df, (pd.Series, pd.DataFrame)):\n      if pipeline is None:\n        raise ValueError(\n            'Pipeline keyword required for non-deferred dataframe conversion.')\n      deferred = pipeline | '%s_Defer%s' % (label, ix) >> beam.Create([df])\n      deferred_dataframes.append(\n          frame_base.DeferredFrame.wrap(\n              expressions.PlaceholderExpression(df.iloc[:0], deferred)))\n    else:\n      raise TypeError(\n          'Unable to convert objects of type %s to a PCollection' % type(df))\n  dataframes = tuple(deferred_dataframes)\n\n  def extract_input(placeholder):\n    if not isinstance(placeholder._reference, pvalue.PCollection):\n      raise TypeError(\n          'Expression roots must have been created with to_dataframe.')\n    return placeholder._reference\n\n  placeholders = frozenset.union(\n      frozenset(), *[df._expr.placeholders() for df in dataframes])\n\n  # Exclude any dataframes that have already been converted to PCollections.\n  # We only want to convert each DF expression once, then re-use.\n  new_dataframes = [\n      df for df in dataframes if df._expr._id not in TO_PCOLLECTION_CACHE\n  ]\n  if len(new_dataframes):","sourceCodeStart":216,"sourceCodeEnd":252,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/dataframe/convert.py#L216-L252","documentation":"apache_beam.dataframe.convert.to_pcollection only accepts DeferredFrame objects (created via to_dataframe), pandas DataFrames (requiring an explicit pipeline=), or existing PCollections. If the input is none of these — e.g. a plain Python list, dict, Series, or other object — it raises this TypeError because the converter has no strategy to turn that type into a PCollection.","triggerScenarios":"Calling convert.to_pcollection(obj) where obj is not a pandas DataFrame, DeferredFrame, or PValue/PCollection — e.g. passing a pandas Series, a list of dicts, a numpy array, or a dict directly.","commonSituations":"Passing a pd.Series instead of a DataFrame after a column selection; forgetting pipeline= when passing a plain DataFrame (that raises a related error first); users assuming to_pcollection works like beam.Create on arbitrary Python values; upgrading code that previously passed lists to beam.Create and swapping in to_pcollection.","solutions":["Check type(df); convert unsupported inputs to a pandas DataFrame first (e.g. Series.to_frame(), pd.DataFrame(list)).","For plain Python data use beam.Create directly instead of to_pcollection.","If passing a real DataFrame without pipeline=, supply the pipeline= keyword argument.","Ensure any dataframe you got from elsewhere was produced by convert.to_dataframe, not constructed ad hoc."],"exampleFix":"// before\npcoll = convert.to_pcollection(series)\n// after\npcoll = convert.to_pcollection(series.to_frame(), pipeline=pipeline)","handlingStrategy":"validation","validationCode":"if not isinstance(obj, (pd.DataFrame, pd.Series, pvalue.PCollection)) or isinstance(obj, pd.Series) and True:\n    # normalize before calling\n    obj = obj.to_frame() if isinstance(obj, pd.Series) else obj","typeGuard":"def is_convertible_to_pcollection(obj) -> bool:\n    import pandas as pd\n    return isinstance(obj, (pd.DataFrame,)) or hasattr(obj, 'pipeline')","tryCatchPattern":null,"preventionTips":["Only pass DataFrames produced by convert.to_dataframe or concrete pd.DataFrame (with pipeline=) into to_pcollection.","Convert Series/lists/dicts to pd.DataFrame before conversion.","Keep dataframe conversions at explicit pipeline-boundary points, not scattered through logic."],"tags":["python","apache-beam","dataframe-api","type-error"],"backgroundTag":"type-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}