mlflow/mlflow · error · MlflowException

INVALID_PARAMETER_VALUE

INVALID_PARAMETER_VALUE

Error message

traces must have a 'trace' column like the result of mlflow.search_traces()

What it means

LabelingSession.add_traces accepts a list of Trace objects, JSON strings, or a pandas DataFrame from mlflow.search_traces(). When a DataFrame is passed, MLflow requires the 'trace' column (search_traces' output format) and raises this error if it is missing.

Source

Thrown at mlflow/genai/labeling/labeling.py:184

        .. note::
            This functionality is only available in Databricks. Please run
            `pip install mlflow[databricks]` to use it.

        Args:
            traces: Can be either:
                a) a pandas DataFrame with a 'trace' column. The 'trace' column should contain
                either `mlflow.entities.Trace` objects or their json string representations.
                b) an iterable of `mlflow.entities.Trace` objects.
                c) an iterable of json string representations of `mlflow.entities.Trace` objects.

        Returns:
            LabelingSession: The updated labeling session.
        """
        import pandas as pd

        if isinstance(traces, pd.DataFrame):
            if "trace" not in traces.columns:
                raise MlflowException(
                    "traces must have a 'trace' column like the result of mlflow.search_traces()",
                    error_code=INVALID_PARAMETER_VALUE,
                )
            traces = traces["trace"].to_list()

        trace_list: list[Trace] = []
        for trace in traces:
            if isinstance(trace, str):
                trace_list.append(Trace.from_json(trace))
            elif isinstance(trace, Trace):
                trace_list.append(trace)
            elif trace is None:
                raise MlflowException(
                    "trace cannot be None. Must be mlflow.entities.Trace or its json string "
                    "representation.",
                    error_code=INVALID_PARAMETER_VALUE,
                )
            else:

View on GitHub (pinned to 6a27f2decc)

Solutions

1. Pass the DataFrame exactly as returned by mlflow.search_traces().
2. Rename your column: df = df.rename(columns={'trace_json': 'trace'}) before calling.
3. Or extract the list yourself: add_traces(df['trace'].to_list()).
4. Or pass a plain list of Trace objects / JSON strings instead of a DataFrame.

Example fix

// before
session.add_traces(df)  # df has 'trace_id' column
// after
session.add_traces(df.rename(columns={'trace_id': 'trace'}))

import pandas as pd
if isinstance(traces, pd.DataFrame):
    assert "trace" in traces.columns, "DataFrame must contain 'trace' column"

def is_search_traces_df(df) -> bool:
    import pandas as pd
    return isinstance(df, pd.DataFrame) and "trace" in df.columns

try:
    session.add_traces(df)
except MlflowException as e:
    if "'trace' column" in str(e):
        session.add_traces(df["trace_id"].rename("trace").to_list())

When it happens

Trigger: Passing a DataFrame lacking a 'trace' column to labeling_session.add_traces(df) — e.g. a manually built DataFrame or one from a different API.

Common situations: Renaming or dropping columns after search_traces; using a DataFrame from export tools with different column names; constructing traces DataFrame by hand.

Related errors

• num_test_cases must be >= 1, got {num_test_cases}
• The 'inputs' column must be a dictionary of field names and
• Invalid endpoint URI: {endpoint_uri}. The endpoint URI must
• Unsupported endpoint schema: {schema}. Expected 'endpoints'
• Dataset row must contain at least one non-None value

AI-assisted analysis of mlflow/mlflow@6a27f2decc (2026-08-29). Data as JSON: /api/errors/4fbde7678f5381ae. Report an issue: GitHub.