build_relationship_index_create requires at least one field

Error message

build_relationship_index_create requires at least one field

What it means

Input guard in the FalkorDB Cypher builder: a relationship index needs at least one property, so an empty fields sequence would render invalid Cypher (CREATE INDEX ... ON ()). Raised before the query is sent so the failure is attributable to the caller's schema rather than the database. Occurs when the relationship type's declared index fields list is empty; supply at least one field.

Source

Thrown at python/cocoindex/connectors/falkordb/_cypher.py:161

    """``CREATE INDEX FOR (e:`Label`) ON (e.`f1`, e.`f2`, ...)``."""
    if not fields:
        raise ValueError("build_node_index_create requires at least one field")
    field_list = ", ".join(f"e.{_quote(f)}" for f in fields)
    return f"CREATE INDEX FOR (e:{_quote(label)}) ON ({field_list})"


def build_node_index_drop(label: str, fields: Sequence[str]) -> str:
    """``DROP INDEX FOR (e:`Label`) ON (e.`f1`, ...)``."""
    if not fields:
        raise ValueError("build_node_index_drop requires at least one field")
    field_list = ", ".join(f"e.{_quote(f)}" for f in fields)
    return f"DROP INDEX FOR (e:{_quote(label)}) ON ({field_list})"


def build_relationship_index_create(rel_type: str, fields: Sequence[str]) -> str:
    """``CREATE INDEX FOR ()-[e:`RelType`]-() ON (e.`f1`, ...)``."""
    if not fields:
        raise ValueError("build_relationship_index_create requires at least one field")
    field_list = ", ".join(f"e.{_quote(f)}" for f in fields)
    return f"CREATE INDEX FOR ()-[e:{_quote(rel_type)}]-() ON ({field_list})"


def build_relationship_index_drop(rel_type: str, fields: Sequence[str]) -> str:
    """``DROP INDEX FOR ()-[e:`RelType`]-() ON (e.`f1`, ...)``."""
    if not fields:
        raise ValueError("build_relationship_index_drop requires at least one field")
    field_list = ", ".join(f"e.{_quote(f)}" for f in fields)
    return f"DROP INDEX FOR ()-[e:{_quote(rel_type)}]-() ON ({field_list})"


def build_vector_index_create(
    label: str,
    field: str,
    dimension: int,
    metric: str,
) -> str:

View on GitHub (pinned to e84aa99b32)

Solutions

Pass at least one relationship property to index.
Skip the index declaration if no property needs indexing.
Check upstream config parsing to see why the fields list is empty.

Example fix

// before
build_relationship_index_create(rel_type="WORKS_AT", fields=[])
// after
build_relationship_index_create(rel_type="WORKS_AT", fields=["since"])

Defensive patterns

Strategy: validation

Validate before calling

if not fields:
    raise ValueError('relationship index requires at least one field')
cypher = build_relationship_index_create(rel_type, fields)

Type guard

def indexable(fields: object) -> bool:
    return isinstance(fields, (list, tuple)) and len(fields) > 0 and all(isinstance(f, str) for f in fields)

Try / catch

try:
    cypher = build_relationship_index_create(rel_type, fields)
except ValueError as e:
    logger.warning('skipping relationship index on %s: %s', rel_type, e)
    cypher = None

Prevention

Declare relationship indexes only when at least one relationship property needs indexing.
Validate the index spec (type + fields) when the schema is loaded.
Ensure field names match actual relationship properties so filters don't drop them all.

When it happens

Trigger: Calling build_relationship_index_create(rel_type, fields=[]) — a relationship index spec with a type but no properties.

Common situations: Relationship index config defaulted to empty; field names filtered out because they didn't match relationship properties; user assumed relationship indexes need no fields.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/994555a6ce8c52fd. Report an issue: GitHub.