What causes "build_node_index_create requires at least one field" in cocoindex-io/cocoindex?

Pass at least one property name in fields (typically a frequently filtered property).

build_node_index_create requires at least one field

Error message

build_node_index_create requires at least one field

What it means

build_node_index_create() requires at least one field because it emits CREATE INDEX ... ON (e.f1, ...) and an index over an empty field list is invalid Cypher. It fails fast rather than generating a query FalkorDB would reject.

Source

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

    """``MATCH ()-[r:`RelType` {pk: $key_0, ...}]->() DELETE r``.

    Endpoints are intentionally not deleted — they're tracked by their own
    table handlers and will be deleted by their own reconciler if orphaned.
    """
    if not pk_fields:
        raise ValueError(
            "build_relationship_delete requires at least one primary key field"
        )
    return (
        f"MATCH ()-[r:{_quote(rel_type)} "
        f"{_key_clause('key', pk_fields, 'r')}]->() DELETE r"
    )


def build_node_index_create(label: str, fields: Sequence[str]) -> str:
    """``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})"

View on GitHub (pinned to e84aa99b32)

Solutions

Pass at least one property name in fields (typically a frequently filtered property).
If no index is actually needed, skip the index declaration entirely instead of passing an empty list.
Check why the fields list is empty upstream (config parsing or name filtering).

Example fix

// before
build_node_index_create(label="Person", fields=[])
// after
build_node_index_create(label="Person", fields=["name"])

Defensive patterns

Strategy: validation

Validate before calling

if not fields:
    raise ValueError('node index requires at least one field; skip the index instead')
cypher = build_node_index_create(label, 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_node_index_create(label, fields)
except ValueError as e:
    logger.warning('skipping index on %s: %s', label, e)
    cypher = None

Prevention

Only declare an index when there is at least one property worth indexing; otherwise omit it entirely.
Validate index specs at config load: label present AND fields non-empty.
Ensure indexed field names match actual schema columns so filtering doesn't silently empty the list.

When it happens

Trigger: Calling build_node_index_create(label, fields=[]) — e.g. an index specification in the target schema lists a label but no properties.

Common situations: Index config defined as an empty list by default and never populated; fields filtered out because names didn't match schema columns; copy-pasted index declaration with fields left blank.

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/320b87c511758110. Report an issue: GitHub.