pathwaycom/pathway · error · ValueError

'{format}' format without explicit 'value' specification can

Error message

'{format}' format without explicit 'value' specification can only be used with single-column tables

What it means

Raised by MessageQueueOutputFormat.build for format='raw' or 'plaintext' when 'value' is not given and the table has more than one column. In raw mode the payload must be exactly one column; with no explicit value= the writer can only proceed if the table has a single column to use implicitly, so multi-column tables are rejected.

Source

Thrown at python/pathway/io/_utils.py:579

                value_fields=_format_output_value_fields(table),
                delimiter=delimiter,
                schema_registry_settings=maybe_schema_registry_settings(
                    schema_registry_settings
                ),
                subject=subject,
            )
        elif format == "raw" or format == "plaintext":
            value_field_index = None
            if key is not None and value is None:
                raise ValueError("'value' must be specified if 'key' is not None")
            if value is not None:
                value_field_index = cls.add_column_reference_to_extract(
                    value, columns_to_extract, extracted_field_indices
                )
            else:
                column_names = list(table._columns.keys())
                if len(column_names) != 1:
                    raise ValueError(
                        f"'{format}' format without explicit 'value' specification "
                        "can only be used with single-column tables"
                    )
                value = table[column_names[0]]
                value_field_index = cls.add_column_reference_to_extract(
                    value, columns_to_extract, extracted_field_indices
                )

            table = table.select(*columns_to_extract)
            if (
                allowed_value_types is not None
                and table[value._name]._column.dtype not in allowed_value_types
            ):
                raise ValueError(
                    f"The value column must have one of the following types: {allowed_value_types}"
                )

            data_format = api.DataFormat(

View on GitHub (pinned to fa2f74a464)

Solutions

Select the single payload column before writing: t = t.select(pw.this.payload).
Or pass value=pw.this.payload explicitly to designate the payload column.
If all columns must be serialized, use format='json' or 'dsv' instead.

Example fix

# before
pw.io.kafka.write(t, ..., format='raw')  # t has 3 columns

# after
t = t.select(pw.this.payload)
pw.io.kafka.write(t, ..., format='raw')

Defensive patterns

Strategy: validation

Validate before calling

if format in ('raw', 'plaintext') and value is None:
    assert len(table.column_names()) == 1, "raw/plaintext implicit value needs a single-column table; select one column first"

Type guard

def raw_ready(table, value) -> bool:
    return value is not None or len(table.column_names()) == 1

Try / catch

try:
    pw.io.kafka.write(t, ..., format='raw')
except ValueError as e:
    if 'single-column tables' in str(e):
        pw.io.kafka.write(t.select(pw.this.payload), ..., format='raw')
    else:
        raise

Prevention

Project to the payload column explicitly before raw writes instead of relying on single-column detection.
When a table gains columns, revisit raw sinks that depended on the single-column shape.

When it happens

Trigger: pw.io.kafka.write(t, ..., format='raw') where t has columns id, payload, ts; prototyping with a single-column table that later gains columns; plaintext forwarding of full rows without selecting one column.

Common situations: Pipelines that evolve: an initially single-column table gains metadata columns and the raw writer starts failing; passing an entire wide table where only one column is the payload.

Related errors

AI-assisted analysis of pathwaycom/pathway@fa2f74a464 (2026-08-15). Data as JSON: /api/errors/8cc5d15fd7d86cb9. Report an issue: GitHub.