pathwaycom/pathway · error · ValueError

metadata column {col._name!r} does not belong to the provide

Error message

metadata column {col._name!r} does not belong to the provided table. Pass column references from the same table, e.g. table.{col._name}.

What it means

Like text_column, every column in metadata_columns of pw.io.leann.write must belong to the table passed as the first argument. Pathway checks each reference's bound table and raises this ValueError for the first mismatch, suggesting the correct reference form table.<name>.

Source

Thrown at python/pathway/io/leann/__init__.py:270

    >>> pw.run()  # doctest: +SKIP
    """
    _check_entitlements("leann")
    _check_leann_available()

    if text_column._table is not table:
        raise ValueError(
            f"text_column {text_column._name!r} does not belong to the provided "
            f"table. Pass a column reference from the same table, "
            f"e.g. text_column=table.{text_column._name}."
        )
    _check_str_column(text_column, "text_column")

    metadata_col_names: list[str] | None = None
    if metadata_columns is not None:
        for col in metadata_columns:
            if col._table is not table:
                raise ValueError(
                    f"metadata column {col._name!r} does not belong to the provided "
                    f"table. Pass column references from the same table, "
                    f"e.g. table.{col._name}."
                )
            _check_str_column(col, "metadata column")
        metadata_col_names = [col._name for col in metadata_columns]

    # Import here to avoid circular import
    from pathway.io.python import write as python_write

    observer = _LeannObserver(
        index_path=index_path,
        text_column=text_column._name,
        metadata_columns=metadata_col_names,
        backend_name=backend_name,
        embedding_mode=embedding_mode,
        embedding_model=embedding_model,
        embedding_options=embedding_options,

View on GitHub (pinned to fa2f74a464)

Solutions

Join or select all needed metadata columns into the single table passed to write(), then reference them from that table
Build metadata_columns as [table[c] for c in names] right before the call so references always match
Check table == col._table for each column before calling if references come from dynamic code

Example fix

# before
enriched = table.join(authors, table.aid == authors.id)
pw.io.leann.write(table, "idx", table.text, metadata_columns=[enriched.name])

# after
enriched = table.join(authors, table.aid == authors.id).select(table.text, author=authors.name)
pw.io.leann.write(enriched, "idx", enriched.text, metadata_columns=[enriched.author])

Defensive patterns

Strategy: validation

Validate before calling

for col in metadata_columns or []:
    assert col._table is table, f"metadata column {col._name!r} not from the written table"
_ = [table[c._name] for c in metadata_columns or []]  # canonical references

Type guard

def all_columns_from(table: pw.Table, cols: list[pw.ColumnReference]) -> bool:
    return all(c._table is table for c in cols)

Try / catch

try:
    pw.io.leann.write(table, "idx", table.text, metadata_columns=cols)
except ValueError as e:
    if "does not belong to the provided table" in str(e):
        cols = [table[c._name] for c in cols]
        pw.io.leann.write(table, "idx", table.text, metadata_columns=cols)
    else:
        raise

Prevention

Flatten joins into one table before the connector call
Build metadata_columns as table[name] lookups at the call site
Assert col._table is table for every column passed to sinks

When it happens

Trigger: pw.io.leann.write(table, path, text_column=table.text, metadata_columns=[other.author]) where other is any table other than the one passed (e.g. a join partner or an earlier transform stage).

Common situations: Collecting metadata columns from several sources (joins) and forgetting to flatten them into one table; passing columns from a table before with_columns renames.

Related errors

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