CSVToDocument(row): 'content_column' is required in run() wh

Error message

CSVToDocument(row): 'content_column' is required in run() when conversion_mode='row'.

What it means

In row conversion mode, CSVToDocument converts each CSV row into its own Document and needs to know which column holds the text. content_column may only be given at run() time in this mode, and if it is missing the component raises instead of guessing a column.

Source

Thrown at haystack/components/converters/csv.py:148

                )
                continue

            merged_metadata = {**bytestream.meta, **metadata}

            if not self.store_full_path and "file_path" in bytestream.meta:
                file_path = bytestream.meta.get("file_path")
                if file_path:  # Ensure the value is not None for mypy
                    merged_metadata["file_path"] = os.path.basename(file_path)

            # Mode: file (backward-compatible default) -> one Document per file
            if self.conversion_mode == "file":
                documents.append(Document(content=data, meta=merged_metadata))
                continue

            # --- ROW MODE (strict) ---
            # Require content_column in run(); no fallback
            if not content_column:
                raise ValueError(
                    "CSVToDocument(row): 'content_column' is required in run() when conversion_mode='row'."
                )

            # Warn for large CSVs in row mode (memory consideration)
            try:
                size_bytes = len(raw)
                if size_bytes > _ROW_MODE_SIZE_WARN_BYTES:
                    logger.warning(
                        "CSVToDocument(row): parsing a large CSV (~{mb:.1f} MB). "
                        "Consider chunking/streaming if you hit memory issues.",
                        mb=size_bytes / (1024 * 1024),
                    )
            except Exception:
                pass

            # Create DictReader; if this fails, raise (no fallback)
            try:
                # ``restkey`` ensures surplus fields on ragged rows (rows with more values than the

View on GitHub (pinned to e318778c9b)

Solutions

Pass content_column='your_column_name' to run().
Confirm conversion_mode='row' is intended; if you want whole-file documents, use the default mode.
Read the column name from the actual CSV header and wire it into the pipeline input.
Validate the run() kwargs in pipeline YAML against the component's run signature.

Example fix

// before
result = csv_conv.run(sources=[file])
// after
result = csv_conv.run(sources=[file], content_column="text")

Defensive patterns

Strategy: validation

Validate before calling

def validate_row_mode_args(mode, content_column):
    if mode == "row" and not content_column:
        raise ValueError("content_column is required when conversion_mode='row'")
validate_row_mode_args(conv.conversion_mode, content_column)

Try / catch

try:
    result = conv.run(sources=sources, content_column=content_column)
except ValueError as e:
    if "content_column" in str(e):
        raise RuntimeError("Pipeline misconfigured: pass content_column for row mode") from e
    raise

Prevention

Always supply content_column when conversion_mode='row'.
Read the CSV header first and use one of its exact column names.
Keep mode and content_column together in pipeline config/wiring.
Write a smoke test calling run() on a small fixture CSV.

When it happens

Trigger: Calling CSVToDocument(conversion_mode='row').run(sources=[...]) without the content_column keyword argument, or passing content_column=None/empty string.

Common situations: Pipelines built for default 'document' mode later switched to 'row' mode in component init without updating the run() call; content_column stored in pipeline config but not wired to run() inputs.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/843f6054bf89d943. Report an issue: GitHub.