From bd3dd6a8e5b8b3b1e176fe309bc4eadb56ee3d47 Mon Sep 17 00:00:00 2001
From: Dhruv <140686560+dask-58@users.noreply.github.com>
Date: Tue, 10 Feb 2026 05:58:50 +0530
Subject: [PATCH] fix: improve error message for multi-field FTS index creation
 (#3005)

Fixes #2999

The error message previously said `"field_names must be a string when
use_tantivy=False"` implying they should use the to be deprecated
tantivy backend #2998.

Updated the error message and docstring to instead guide users to create
a separate FTS index for each field

Signed-off-by: dask-58 <googldhruv@gmail.com>
---
 python/python/lancedb/table.py | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/python/python/lancedb/table.py b/python/python/lancedb/table.py
index 969332355..b006586a8 100644
--- a/python/python/lancedb/table.py
+++ b/python/python/lancedb/table.py
@@ -904,7 +904,9 @@ class Table(ABC):
         ----------
         field_names: str or list of str
             The name(s) of the field to index.
-            can be only str if use_tantivy=True for now.
+            If ``use_tantivy`` is False (default), only a single field name
+            (str) is supported. To index multiple fields, create a separate
+            FTS index for each field.
         replace: bool, default False
             If True, replace the existing index if it exists. Note that this is
             not yet an atomic operation; the index will be temporarily
@@ -2298,7 +2300,11 @@ class LanceTable(Table):
     ):
         if not use_tantivy:
             if not isinstance(field_names, str):
-                raise ValueError("field_names must be a string when use_tantivy=False")
+                raise ValueError(
+                    "Native FTS indexes can only be created on a single field "
+                    "at a time. To search over multiple text fields, create a "
+                    "separate FTS index for each field."
+                )
 
             if tokenizer_name is None:
                 tokenizer_configs = {