{"record":{"id":"14b4e572d7cc9e15","repo":"pathwaycom/pathway","slug":"role-col-name-r-must-be-of-type-str-got-col","errorCode":null,"errorMessage":"{role} {col._name!r} must be of type str, got {col._column.dtype!r}.","messagePattern":"(.+?) (.+?) must be of type str, got (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/pathway/io/leann/__init__.py","lineNumber":128,"sourceCode":"        self.index_path.parent.mkdir(parents=True, exist_ok=True)\n        builder.build_index(str(self.index_path))\n        logger.info(\n            f\"LEANN index built at {self.index_path} with {len(self.documents)} documents\"\n        )\n\n\ndef _check_leann_available() -> None:\n    \"\"\"Check if leann package is available and raise helpful error if not.\"\"\"\n    try:\n        import leann  # noqa: F401\n    except ImportError as e:\n        raise ImportError(_LEANN_INSTALL_ERROR_MESSAGE) from e\n\n\ndef _check_str_column(col: ColumnReference, role: str) -> None:\n    \"\"\"Raise ValueError if *col* is not of type str.\"\"\"\n    if col._column.dtype != dt.STR:\n        raise ValueError(\n            f\"{role} {col._name!r} must be of type str, \" f\"got {col._column.dtype!r}.\"\n        )\n\n\n@check_arg_types\n@trace_user_frame\ndef write(\n    table: Table,\n    index_path: str | os.PathLike,\n    text_column: ColumnReference,\n    *,\n    metadata_columns: list[ColumnReference] | None = None,\n    backend_name: Literal[\"hnsw\", \"diskann\"] = \"hnsw\",\n    embedding_mode: (\n        Literal[\"sentence-transformers\", \"openai\", \"mlx\", \"ollama\"] | None\n    ) = None,\n    embedding_model: str | None = None,\n    embedding_options: dict | None = None,","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/pathwaycom/pathway/blob/fa2f74a4649b7c5908690cf60137263d8d80de5f/python/pathway/io/leann/__init__.py#L110-L146","documentation":"The LEANN sink stores text and metadata as strings, so every column designated as text or metadata must have Pathway dtype pw.STR (dt.STR). _check_str_column raises ValueError naming the offending role ('text_column' or 'metadata column'), the column name, and the actual dtype when this contract is broken.","triggerScenarios":"Calling pw.io.leann.write(table, path, text_column=table.doc_id) where doc_id is INT/ANY/etc.; or listing a metadata column whose dtype is not dt.STR (e.g. an int id or a Json column).","commonSituations":"Passing a numeric id or timestamp column as metadata; columns parsed with schema autodetection that came out as int; columns that hold Optional[str] (dt.STR is still used, but a plain object column from apply() without dtype hints becomes ANY).","solutions":["Cast the column to string before writing: table.col.astype(str) or table.select(txt=pw.this.col.astype(pw.ColumnSchema(dtype=pw.STR)))","Ensure the read schema declares the column as str (class X(Schema): col: str)","Only pass columns you truly need as metadata, converting numeric ids with apply(lambda x: str(x), dtype=pw.STR-like typing)"],"exampleFix":"# before\npw.io.leann.write(t, \"idx\", t.text, metadata_columns=[t.doc_id])  # doc_id is int\n\n# after\nt = t.with_columns(doc_id=t.doc_id.astype(str))\npw.io.leann.write(t, \"idx\", t.text, metadata_columns=[t.doc_id])","handlingStrategy":"type-guard","validationCode":"def is_str_column(col: pw.ColumnReference) -> bool:\n    return col._column.dtype == pw.dt.STR\n\nassert is_str_column(table.text) and all(is_str_column(c) for c in metadata_columns)","typeGuard":"from pathway import dt\n\ndef is_str_column(col: pw.ColumnReference) -> bool:\n    return col._column.dtype == dt.STR","tryCatchPattern":"try:\n    pw.io.leann.write(table, \"idx\", table.text)\nexcept ValueError as e:\n    if \"must be of type str\" in str(e):\n        table = table.with_columns(text=table.text.astype(str))\n    else:\n        raise","preventionTips":["Declare str types explicitly in the read schema for text columns","Cast numeric metadata columns with .astype(str) before the write","Check col._column.dtype == pw.dt.STR in helper code wiring dynamic columns"],"tags":["leann","pathway","dtype","type-mismatch","validation"],"backgroundTag":null,"analyzedSha":"fa2f74a4649b7c5908690cf60137263d8d80de5f","analyzedAt":"2026-08-15T01:48:17.006Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}