apache/beam · error · WontImplementError

melt(ignore_index=True) is order sensitive because it…

Error message

melt(ignore_index=True) is order sensitive because it requires generating a new index based on the order of the data.

What it means

Beam's DataFrame.melt throws WontImplementError when ignore_index=True because generating a fresh sequential index depends on the order of the data, which distributed execution does not preserve. Only ignore_index=False (keeping the original index) is supported.

Solutions

Pass ignore_index=False and keep the existing index.
Reset the index explicitly afterwards if a clean index is needed and order does not matter.
Drop the index column after melt if it is unused.
Fall back to local pandas for ignore_index=True semantics.

Example fix

// before
melted = df.melt()
// after
melted = df.melt(ignore_index=False)

Defensive patterns

Strategy: validation

Validate before calling

def check_melt_args(ignore_index):
    if ignore_index:
        raise ValueError('melt(ignore_index=True) is not supported in Beam DataFrames')

Type guard

def melt_supported(ignore_index) -> bool:
    return not ignore_index

Try / catch

from apache_beam.dataframe import frame_base
try:
    melted = df.melt()
except frame_base.WontImplementError:
    melted = df.melt(ignore_index=False)

Prevention

Always pass ignore_index=False explicitly when melting in Beam.
Do not rely on a fresh sequential index from distributed reshapes.
Reset the index locally after materializing results if needed.

When it happens

Trigger: Calling df.melt() or df.melt(ignore_index=True) on a DeferredDataFrame (ignore_index defaults to True in pandas>=1.1).

Common situations: Unpivoting wide frames in Beam with default melt arguments; users unaware the default itself is order-sensitive.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/dataframe/frames.py:3998

      inplace=True,
      base=pd.DataFrame,
      requires_partition_by=partitionings.Index(),
      preserves_partition_by=partitionings.Arbitrary())

  values = property(frame_base.wont_implement_method(
      pd.DataFrame, 'values', reason="non-deferred-result"))

  style = property(frame_base.wont_implement_method(
      pd.DataFrame, 'style', reason="non-deferred-result"))

  @frame_base.with_docs_from(pd.DataFrame)
  @frame_base.args_to_kwargs(pd.DataFrame)
  @frame_base.populate_defaults(pd.DataFrame)
  def melt(self, ignore_index, **kwargs):
    """``ignore_index=True`` is not supported, because it requires generating an
    order-sensitive index."""
    if ignore_index:
      raise frame_base.WontImplementError(
          "melt(ignore_index=True) is order sensitive because it requires "
          "generating a new index based on the order of the data.",
          reason="order-sensitive")

    return frame_base.DeferredFrame.wrap(
        expressions.ComputedExpression(
            'melt',
            lambda df: df.melt(ignore_index=False, **kwargs), [self._expr],
            requires_partition_by=partitionings.Arbitrary(),
            preserves_partition_by=partitionings.Singleton()))

  if hasattr(pd.DataFrame, 'value_counts'):
    @frame_base.with_docs_from(pd.DataFrame)
    def value_counts(self, subset=None, sort=False, normalize=False,
                     ascending=False, dropna=True):
      """``sort`` is ``False`` by default, and ``sort=True`` is not supported
      because it imposes an ordering on the dataset which likely will not be
      preserved."""

View on GitHub (pinned to 12126d8942)