mlflow/mlflow · error · MlflowException

This model contains a column-based signature, which suggests

Error message

This model contains a column-based signature, which suggests a DataFrame input. There was an error casting the input data to a DataFrame: {e}

What it means

For column-based signatures, MLflow accepts dict, list, ndarray, or Series inputs and casts them to a pandas DataFrame. If that cast throws (e.g. dict values of unequal length or unhashable/mixed structures), the original exception is wrapped in this MlflowException.

Source

Thrown at mlflow/models/utils.py:1211

                    ):
                        # Pandas DataFrames can't be constructed with embedded multi-dimensional
                        # numpy arrays. Accordingly, we convert any multi-dimensional numpy
                        # arrays to lists before constructing a DataFrame. This is safe because
                        # ColSpec model signatures do not support array columns, so subsequent
                        # validation logic will result in a clear "incompatible input types"
                        # exception. This is preferable to a pandas DataFrame construction error
                        pf_input = pd.DataFrame({
                            key: (
                                value.tolist()
                                if (isinstance(value, np.ndarray) and value.ndim > 1)
                                else value
                            )
                            for key, value in pf_input.items()
                        })
                    else:
                        pf_input = pd.DataFrame(pf_input)
                except Exception as e:
                    raise MlflowException(
                        "This model contains a column-based signature, which suggests a DataFrame"
                        " input. There was an error casting the input data to a DataFrame:"
                        f" {e}"
                    )
        elif isinstance(pf_input, (list, np.ndarray, pd.Series)):
            pf_input = pd.DataFrame(pf_input)
        elif HAS_PYSPARK and isinstance(pf_input, SparkDataFrame):
            pf_input = pf_input.limit(10).toPandas()
            for field in original_pf_input.schema.fields:
                if isinstance(field.dataType, (StructType, ArrayType)):
                    pf_input[field.name] = pf_input[field.name].apply(
                        lambda row: convert_complex_types_pyspark_to_pandas(row, field.dataType)
                    )
        if not isinstance(pf_input, pd.DataFrame):
            raise MlflowException(
                f"Expected input to be DataFrame. Found: {type(pf_input).__name__}"
            )

View on GitHub (pinned to 6a27f2decc)

Solutions

Construct the DataFrame yourself first and fix the data (pad/truncate lists, align keys), then pass the DataFrame to predict.
Ensure dict values are equal-length lists/arrays/Series.
Normalize records with pd.DataFrame(records) explicitly and inspect the error before calling the model.

Example fix

// before
model.predict({"a": [1, 2, 3], "b": [4, 5]})  # unequal lengths

// after
df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
model.predict(df)

Defensive patterns

Strategy: validation

Validate before calling

import pandas as pd

def as_safe_df(d):
    if isinstance(d, dict):
        lengths = {len(v) for v in d.values() if hasattr(v, "__len__")}
        if len(lengths) > 1:
            raise ValueError(f"dict values have unequal lengths: {lengths}")
    return pd.DataFrame(d)  # raises locally with a clear traceback

Type guard

def is_df_castable(d):
    return isinstance(d, (dict, list, np.ndarray, pd.Series, pd.DataFrame))

Try / catch

from mlflow.exceptions import MlflowException
try:
    model.predict(data)
except MlflowException as e:
    if "casting the input data to a DataFrame" in str(e):
        model.predict(pd.DataFrame(data))  # original pandas error surfaces
    else:
        raise

Prevention

Construct the DataFrame yourself so pandas errors are not wrapped
Ensure dict-of-lists values are equal length
Normalize list-of-dicts records to consistent keys

When it happens

Trigger: Predict/validate_schema with a dict of lists with different lengths, a list of dicts with inconsistent keys, or a jagged/ragged structure against a column-based signature where pd.DataFrame(pf_input) raises.

Common situations: Dict-of-arrays with mismatched lengths after partial data loading; list-of-dicts where some records miss keys but numpy conversion is attempted; passing dict of dicts which pandas cannot coerce as intended.

Related errors

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