unslothai/unsloth · error · RuntimeError

pandas is required for unstructured seed processing: {exc}

Error message

pandas is required for unstructured seed processing: {exc}

What it means

RuntimeError raised in the preview path of the unstructured seed chunker when pandas cannot be imported. The plugin imports pandas lazily; the fast path (cached parquet already materialized, returning in-memory rows) never needs it, so this error only fires on the first preview of a file when pandas is genuinely missing from the environment. The original ImportError is chained (raise ... from exc) to preserve the root cause.

Source

Thrown at studio/backend/plugins/data-designer-unstructured-seed/src/data_designer_unstructured_seed/chunking.py:45

    return size, overlap


def build_unstructured_preview_rows(
    *, source_path: Path, preview_size: int, chunk_size: Any, chunk_overlap: Any
) -> list[dict[str, str]]:
    parquet_path, rows = materialize_unstructured_seed_dataset(
        source_path = source_path,
        chunk_size = chunk_size,
        chunk_overlap = chunk_overlap,
    )
    count = max(0, int(preview_size))
    if rows:
        return rows[:count]

    try:
        import pandas as pd
    except ImportError as exc:  # pragma: no cover
        raise RuntimeError(f"pandas is required for unstructured seed processing: {exc}") from exc

    dataframe = pd.read_parquet(parquet_path).head(count)
    return [
        {"chunk_text": str(value.get("chunk_text", "")).strip()}
        for value in dataframe.to_dict(orient = "records")
        if str(value.get("chunk_text", "")).strip()
    ]


def build_multi_file_preview_rows(
    *,
    file_entries: list[tuple[Path, str]],
    preview_size: int,
    chunk_size: int | None,
    chunk_overlap: int | None,
) -> list[dict[str, str]]:
    cs = _to_int(chunk_size, DEFAULT_CHUNK_SIZE)
    co = _to_int(chunk_overlap, DEFAULT_CHUNK_OVERLAP)

View on GitHub (pinned to 203007d190)

Solutions

1. Install pandas into the environment running the backend: pip install pandas.
2. Reinstall both pandas and numpy together if the chained ImportError mentions a binary incompatibility.
3. Add pandas to the plugin's dependency extras in deployment manifests.

Example fix

# before
$ pip install data-designer-unstructured-seed  # no pandas

# after
$ pip install data-designer-unstructured-seed pandas

def pandas_importable() -> bool:
    try:
        import pandas  # noqa: F401
        return True
    except ImportError:
        return False

assert pandas_importable(), "install pandas before previewing unstructured seeds"

When it happens

Trigger: Calling the preview function on a not-yet-cached source file in a Python environment where pandas (or a pandas dependency like numpy) is not installed or is a broken install.

Common situations: Installing the plugin without its optional extras; a venv built from a trimmed requirements list; numpy/pandas ABI mismatch after a partial upgrade producing ImportError at import time.

Related errors

• NeMo Data Designer Hugging Face integration is not installed
• GPU selection is unavailable on this host: {exc}
• '{family_name}' needs diffusers ({pipeline_class}), which th
• '{family_name}' needs diffusers ({pipeline_class}), but this
• Unsloth: MLX inference requires unsloth-zoo with the MLX mod

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/bd3eca9d6ccccab7. Report an issue: GitHub.