{"record":{"id":"f0b315ca5f79b412","repo":"apache/beam","slug":"encountered-an-unnamed-index-cannot-convert-to-a-schema","errorCode":null,"errorMessage":"Encountered an unnamed index. Cannot convert to a schema-aware PCollection with include_indexes=True. Please name all indexes or consider not including indexes.","messagePattern":"Encountered an unnamed index\\. Cannot convert to a schema-aware PCollection with include_indexes=True\\. Please name all indexes or consider not including indexes\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/dataframe/schemas.py","lineNumber":143,"sourceCode":"          \"include_indexes=True for a Series input. Note that this \"\n          \"parameter is _not_ respected for DeferredSeries \"\n          \"conversion.\")\n    return dtype_to_fieldtype(proxy.dtype)\n  else:\n    raise TypeError(f\"Proxy '{proxy}' has unsupported type '{type(proxy)}'\")\n\n\ndef element_typehint_from_dataframe_proxy(\n    proxy: pd.DataFrame, include_indexes: bool = False) -> RowTypeConstraint:\n\n  output_columns = []\n  if include_indexes:\n    remaining_index_names = list(proxy.index.names)\n    i = 0\n    while len(remaining_index_names):\n      index_name = remaining_index_names.pop(0)\n      if index_name is None:\n        raise ValueError(\n            \"Encountered an unnamed index. Cannot convert to a \"\n            \"schema-aware PCollection with include_indexes=True. \"\n            \"Please name all indexes or consider not including \"\n            \"indexes.\")\n      elif index_name in remaining_index_names:\n        raise ValueError(\n            \"Encountered multiple indexes with the name '%s'. \"\n            \"Cannot convert to a schema-aware PCollection with \"\n            \"include_indexes=True. Please ensure all indexes have \"\n            \"unique names or consider not including indexes.\" % index_name)\n      elif index_name in proxy.columns:\n        raise ValueError(\n            \"Encountered an index that has the same name as one \"\n            \"of the columns, '%s'. Cannot convert to a \"\n            \"schema-aware PCollection with include_indexes=True. \"\n            \"Please ensure all indexes have unique names or \"\n            \"consider not including indexes.\" % index_name)\n      else:","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/dataframe/schemas.py#L125-L161","documentation":"When converting a DataFrame proxy to a schema-aware PCollection with include_indexes=True, every index level must have a name so it can map to a schema field. An index level whose name is None makes the mapping ambiguous, so ValueError is raised.","triggerScenarios":"Calling infer_output_type / element_type_from_dataframe (or a schema-aware output of a DataFrame transform) with include_indexes=True on a DataFrame whose index (or any MultiIndex level) is unnamed.","commonSituations":"DataFrames created from raw lists/arrays with default RangeIndex; after groupby/reset operations that leave None-named index levels; porting pandas code that never names its index.","solutions":["Name the index before conversion: df.index.name = 'id' (or rename each MultiIndex level via df.index.names = [...])","Call reset_index() and rename the resulting columns, then convert with include_indexes=False","Set include_indexes=False if the index values are not needed in the schema"],"exampleFix":"// before\ndf = pd.DataFrame({'a': [1,2]}); beam.dataframe.convert.to_pcollection(df, include_indexes=True)\n// after\ndf.index.name = 'row_id'\nbeam.dataframe.convert.to_pcollection(df, include_indexes=True)","handlingStrategy":"validation","validationCode":"if include_indexes and any(n is None for n in proxy.index.names):\n    proxy.index.names = [n or f'index_{i}' for i, n in enumerate(proxy.index.names)]","typeGuard":"def has_named_index(df) -> bool:\n    return all(n is not None for n in df.index.names)","tryCatchPattern":"try:\n    pc = beam.dataframe.convert.to_pcollection(df, include_indexes=True)\nexcept ValueError as e:\n    if 'unnamed index' in str(e):\n        df.index.name = 'row_id'\n        pc = beam.dataframe.convert.to_pcollection(df, include_indexes=True)","preventionTips":["Name all index levels before schema-aware conversion","Prefer reset_index() + named columns over include_indexes=True","Validate index.names during pipeline construction, not at runtime"],"tags":["python","apache-beam","dataframe","schema","index"],"backgroundTag":"schema-validation-failed","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"}