redis/redis-py · error · ValueError

At least one tag must be specified

Error message

At least one tag must be specified

What it means

Raised by redis.commands.search.querystring.tags() when called with no positional arguments. The helper builds a tag query value ({tag1 | tag2}); with no tags there is nothing to match, which is almost always a caller bug.

Solutions

1. Guard before calling: only call tags(*items) when items is non-empty.
2. If an empty tag set means 'no filter', omit the tag condition from the querystring entirely.
3. Provide at least one tag value.

Example fix

// before
node = intersect(category=tags(*user_categories))
// after
if user_categories:
    node = intersect(category=tags(*user_categories))
else:
    node = intersect()  # no category constraint

if tags_list:
    val = tags(*tags_list)
else:
    val = None  # omit the tag condition

try:
    val = tags(*items)
except ValueError:
    val = None

When it happens

Trigger: Calling tags() with no args, or tags(*[]) where the unpacked list is empty. Building a dynamic tag query from a list that happens to be empty.

Common situations: User-selected filter that produced zero tags. Code that maps an empty collection through tags() without a guard.

Related errors

• Bad query type
• collect fields must be '*' or a non-empty list of names
• collect sort_by must contain at least one field
• Did not receive a Filter object.
• Did not receive a SortByField.

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

Appendix: source

Thrown at redis/commands/search/querystring.py:10

def tags(*t):
    """
    Indicate that the values should be matched to a tag field

    ### Parameters

    - **t**: Tags to search for
    """
    if not t:
        raise ValueError("At least one tag must be specified")
    return TagValue(*t)


def between(a, b, inclusive_min=True, inclusive_max=True):
    """
    Indicate that value is a numeric range
    """
    return RangeValue(a, b, inclusive_min=inclusive_min, inclusive_max=inclusive_max)


def equal(n):
    """
    Match a numeric value
    """
    return between(n, n)


def lt(n):

View on GitHub (pinned to 6a6b581b48)