From 217fd8491d070ab8528c20134221bed66ac686eb Mon Sep 17 00:00:00 2001
From: whitewooood <975177209@qq.com>
Date: Thu, 18 Jun 2026 03:55:55 +0800
Subject: [PATCH] fix(python): clarify single dictionary input error (#3537)

## Summary
- clarify the Python error for passing a single dictionary to table
creation/add paths
- add a regression test for `create_table(..., data=dict)` so it points
users to a list of dictionaries

Fixes #409

## Testing
- `python -m pytest python/tests/test_table.py -q`
- `python -m ruff format python/lancedb/table.py
python/lancedb/scannable.py python/tests/test_table.py`
- `python -m ruff check python/lancedb/table.py
python/lancedb/scannable.py python/tests/test_table.py`
---
 python/python/lancedb/scannable.py |  5 ++++-
 python/python/lancedb/table.py     |  5 ++++-
 python/python/tests/test_table.py  | 14 ++++++++++++--
 3 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/python/python/lancedb/scannable.py b/python/python/lancedb/scannable.py
index beccc8f2e..b26aac2fa 100644
--- a/python/python/lancedb/scannable.py
+++ b/python/python/lancedb/scannable.py
@@ -86,7 +86,10 @@ def _from_list(data: list) -> Scannable:
 
 @to_scannable.register(dict)
 def _from_dict(data: dict) -> Scannable:
-    raise ValueError("Cannot add a single dictionary to a table. Use a list.")
+    raise ValueError(
+        "Cannot create or add rows from a single dictionary. "
+        "Use a list of dictionaries instead."
+    )
 
 
 @to_scannable.register(LanceModel)
diff --git a/python/python/lancedb/table.py b/python/python/lancedb/table.py
index c124309c3..12061df49 100644
--- a/python/python/lancedb/table.py
+++ b/python/python/lancedb/table.py
@@ -243,7 +243,10 @@ def _into_pyarrow_reader(
         raise ValueError("Cannot add a single LanceModel to a table. Use a list.")
 
     if isinstance(data, dict):
-        raise ValueError("Cannot add a single dictionary to a table. Use a list.")
+        raise ValueError(
+            "Cannot create or add rows from a single dictionary. "
+            "Use a list of dictionaries instead."
+        )
 
     if isinstance(data, list):
         # Handle empty list case
diff --git a/python/python/tests/test_table.py b/python/python/tests/test_table.py
index b30877ade..ff363932e 100644
--- a/python/python/tests/test_table.py
+++ b/python/python/tests/test_table.py
@@ -301,6 +301,16 @@ def test_create_table(mem_db: DBConnection):
         assert expected == tbl
 
 
+def test_create_table_rejects_single_dictionary(mem_db: DBConnection):
+    data = {"vector": [3.1, 4.1], "item": "foo", "price": 10.0}
+    with pytest.raises(ValueError) as excep_info:
+        mem_db.create_table("test", data=data)
+    assert (
+        str(excep_info.value) == "Cannot create or add rows from a single dictionary. "
+        "Use a list of dictionaries instead."
+    )
+
+
 def test_empty_table(mem_db: DBConnection):
     schema = pa.schema(
         [
@@ -330,8 +340,8 @@ def test_add_dictionary(mem_db: DBConnection):
     with pytest.raises(ValueError) as excep_info:
         tbl.add(data=data)
     assert (
-        str(excep_info.value)
-        == "Cannot add a single dictionary to a table. Use a list."
+        str(excep_info.value) == "Cannot create or add rows from a single dictionary. "
+        "Use a list of dictionaries instead."
     )