redis/redis-py · error · ValueError

Cannot use FIELDNAME alias with no field

Error message

Cannot use FIELDNAME alias with no field

What it means

Raised by Reducer.alias() (redis/commands/search/aggregation.py:51) as a ValueError when the special FIELDNAME sentinel is passed as the alias but the reducer has no single field set (self._field is None). FIELDNAME means 'name the output after the input field', which is only meaningful for single-field reducers like Count's peers; multi-field or fieldless reducers cannot derive a name.

Solutions

1. Only use FIELDNAME on reducers that operate on exactly one field (e.g. Sum, Min, Max on '@field').
2. For fieldless reducers like Count, pass an explicit alias string instead.
3. Ensure the reducer's _field is set before calling alias(FIELDNAME).

Example fix

# before
from redis.commands.search.aggregation import Count, Asc, FIELDNAME
Count().alias(FIELDNAME)
# after
Count().alias('total')

def safe_reducer_alias(reducer, alias):
    from redis.commands.search.aggregation import FIELDNAME
    if alias is FIELDNAME and not reducer._field:
        raise ValueError('FIELDNAME alias requires a single-field reducer')
    return reducer.alias(alias)

def reducer_supports_fieldname(reducer) -> bool:
    return bool(getattr(reducer, '_field', None))

try:
    reducer.alias(FIELDNAME)
except ValueError as e:
    if 'FIELDNAME' in str(e):
        reducer.alias('value')  # explicit alias
    else:
        raise

When it happens

Trigger: Calling reducer.alias(FIELDNAME) on a reducer constructed without a field, e.g. Count().alias(FIELDNAME) (Count takes no field) or a reducer whose _field was never set.

Common situations: Copying a FIELDNAME alias pattern from a single-field reducer example onto a zero/multi-field reducer, or refactoring a reducer and dropping its field argument while keeping the alias call.

Related errors

• Bad query
• Bad query type
• collect fields must be '*' or a non-empty list of names
• collect sort_by must contain at least one field
• Must provide AggregateRequest object or Query object.

AI-assisted analysis of redis/redis-py@6a6b581b48 (2026-08-10). Data as JSON: /api/errors/63c1c71467e79dda. Report an issue: GitHub.

Appendix: source

Thrown at redis/commands/search/aggregation.py:51

    def alias(self, alias: str) -> "Reducer":
        """
        Set the alias for this reducer.

        ### Parameters

        - **alias**: The value of the alias for this reducer. If this is the
            special value `aggregation.FIELDNAME` then this reducer will be
            aliased using the same name as the field upon which it operates.
            Note that using `FIELDNAME` is only possible on reducers which
            operate on a single field value.

        This method returns the `Reducer` object making it suitable for
        chaining.
        """
        if alias is FIELDNAME:
            if not self._field:
                raise ValueError("Cannot use FIELDNAME alias with no field")
            else:
                # Chop off initial '@', which is optional in field names
                alias = self._field.removeprefix("@")
        self._alias = alias
        return self

    @property
    def args(self) -> Tuple[str, ...]:
        return self._args


class SortDirection:
    """
    This special class is used to indicate sort direction.
    """

    DIRSTRING: Optional[str] = None

View on GitHub (pinned to 6a6b581b48)