What causes "EXPLAINCLI will not be implemented." in redis/redis-py?

Use client.explain(query) (FT.EXPLAIN) for the execution plan of a query.

redis/redis-py · error · NotImplementedError

EXPLAINCLI will not be implemented.

Error message

EXPLAINCLI will not be implemented.

What it means

Raised unconditionally by explain_cli() — the method is a permanent stub. FT.EXPLAINCLI was removed from RediSearch and the Python client deliberately does not implement it. Any call fails immediately with NotImplementedError rather than emitting an unsupported command.

Source

Thrown at redis/commands/search/commands.py:1423

        if isinstance(res, Pipeline):
            return res

        return self._parse_results(HYBRID_CMD, res, **options)

    def explain(
        self,
        query: Union[str, Query],
        query_params: Optional[Dict[str, Union[str, int, float, bytes]]] = None,
    ):
        """Returns the execution plan for a complex query.

        For more information see `FT.EXPLAIN <https://redis.io/commands/ft.explain>`_.
        """  # noqa
        args, query_text = self._mk_query_args(query, query_params=query_params)
        return self.execute_command(EXPLAIN_CMD, *args)

    def explain_cli(self, query: Union[str, Query]):  # noqa
        raise NotImplementedError("EXPLAINCLI will not be implemented.")

    def aggregate(
        self,
        query: Union[AggregateRequest, Cursor],
        query_params: Optional[Dict[str, Union[str, int, float, bytes]]] = None,
    ):
        """
        Issue an aggregation query.

        ### Parameters

        **query**: This can be either an `AggregateRequest`, or a `Cursor`

        An `AggregateResult` object is returned. You can access the rows from
        its `rows` property, which will always yield the rows of the result.

        For more information see `FT.AGGREGATE <https://redis.io/commands/ft.aggregate>`_.
        """  # noqa

View on GitHub (pinned to da03cdc7e8)

Solutions

Use client.explain(query) (FT.EXPLAIN) for the execution plan of a query.
Remove explain_cli calls from your code entirely.
Use client.profile(query) for combined execution + timing info.

Example fix

// before
client.explain_cli(Query('@title:hello'))
// after
client.explain(Query('@title:hello'))

Defensive patterns

Strategy: try-catch

Validate before calling

def explain_or_profile(client, query, profile=False):
    """Use explain() or profile(); explain_cli() is intentionally unimplemented."""
    if profile:
        return client.profile(query)
    return client.explain(query)

Type guard

null

Try / catch

try:
    client.explain_cli(query)
except NotImplementedError:
    plan = client.explain(query)  # supported equivalent

Prevention

Remove every explain_cli reference from your codebase — it is a permanent stub.
Use explain() for plans and profile() for plans + timing.
Add a grep CI check for 'explain_cli' to catch regressions.

When it happens

Trigger: Call client.explain_cli(query) on a search client — always raises, regardless of arguments.

Common situations: Porting old code or tutorials that reference EXPLAINCLI; assuming a CLI counterpart to explain() exists.

Related errors

AI-assisted analysis of redis/redis-py@da03cdc7e8 (2026-08-04). Data as JSON: /data/errors/92bbdc20a0b10825.json. Report an issue: GitHub.