Bug: KU_UNREACHABLE Error when using .get_as_df() on a query with relationship property filters

[Brad-Edwards]

Imported from kuzudb/kuzu#6029
Original URL: kuzudb#6029
Original author: @AlphaEcho11
Original created at: 2025-09-24T07:30:37Z

Kuzu version

v0.11.2

What operating system are you using?

Windows 11 Pro

What happened?

When executing a Cypher query that filters on relationship properties (e.g., WHERE r.confidence_score < $threshold) and then attempting to convert the result to a Pandas DataFrame using .get_as_df(), Kùzu throws a RuntimeError with a KU_UNREACHABLE assertion failure.

The error suggests a bug within the internal C++ result-to-DataFrame converter, as the Kùzu developers believed the state leading to this error was impossible to reach. The query executes successfully, but the serialization to a DataFrame fails.

A manual iteration over the results using .get_next() works as expected, confirming the issue is specific to the .get_as_df() method for this type of query result

Are there known steps to reproduce?

Steps to Reproduce

The following self-contained Python script reliably reproduces the error. It sets up a minimal graph, runs a query similar to the one causing the issue, and fails on the .get_as_df() call.

Python

import kuzu
import pandas as pd
import os
import shutil

DB_NAME = "repro_db"

Clean up previous runs

if os.path.exists(DB_NAME):
shutil.rmtree(DB_NAME)

1. Setup the database and schema

db = kuzu.Database(DB_NAME)
conn = kuzu.Connection(db)

print("--- Creating Schema ---")
conn.execute("CREATE NODE TABLE Entity(name STRING, PRIMARY KEY (name));")
conn.execute("""
CREATE REL TABLE HasRelationship(
FROM Entity TO Entity,
confidence_score DOUBLE,
status STRING
);
""")

2. Insert minimal data to trigger the bug

print("--- Inserting Data ---")
conn.execute("CREATE (e:Entity {name: 'SubjectA'})")
conn.execute("CREATE (e:Entity {name: 'ObjectB'})")
conn.execute("""
MATCH (a:Entity {name: 'SubjectA'}), (b:Entity {name: 'ObjectB'})
CREATE (a)-[:HasRelationship {confidence_score: 0.5, status: 'unverified'}]->(b)
""")
print("Data inserted.")

3. The query and the line that causes the crash

query = """
MATCH (a)-[r]->(b)
WHERE r.confidence_score < $threshold AND r.status <> 'verified'
RETURN a.name AS subject, label(r) AS relationship, b.name AS object,
r.confidence_score AS score, id(r) AS rel_id
LIMIT 10;
"""
params = {"threshold": 0.7}

print("\n--- Running Query ---")
try:
weak_rels_result = conn.execute(query, params)

print("Query executed successfully. Attempting to convert to DataFrame...")

# THIS IS THE LINE THAT FAILS
df = weak_rels_result.get_as_df() 

print("Successfully created DataFrame:")
print(df)

except RuntimeError as e:
print(f"\n--- ERROR ---")
print(f"Caught the expected RuntimeError: {e}")
print("This confirms the bug in .get_as_df().")

Expected Behavior
The code should execute without error, and a Pandas DataFrame containing the query results should be printed to the console.

Actual Behavior
The script executes the query but fails during the DataFrame conversion, raising the following error:

RuntimeError: Assertion failed in file "[...]\py_query_result_converter.cpp" on line 185
(my exact error was: RuntimeError: Assertion failed in file "C:\Users\runner\AppData\Local\Temp\cibw-sdist-m1tz62cu\sdist\kuzu-source\tools\python_api\src_cpp\py_query_result_converter.cpp" on line 185: KU_UNREACHABLE)

---

Workaround
A reliable workaround is to bypass the .get_as_df() method and manually construct the list of dictionaries by iterating through the query result object. This proves the query itself is sound and the issue is isolated to the converter.

--- WORKAROUND ---

--- This code replaces the failing 'weak_rels_result.get_as_df()' call. ---

print("\n--- Applying Workaround ---")
weak_rels_result = conn.execute(query, params) # Re-run query for demonstration

weak_rels = []
column_names = weak_rels_result.get_column_names()
while weak_rels_result.has_next():
row_values = weak_rels_result.get_next()
weak_rels.append(dict(zip(column_names, row_values)))

print("Successfully built results manually:")
print(pd.DataFrame(weak_rels))