redis/redis-py · error · TypeError

prefix must be provided

Error message

prefix must be provided

What it means

Raised by IndexDefinition._append_prefix when the prefix argument is explicitly None. The RediSearch FT.CREATE auto-indexing definition requires a prefix list to know which keys to index; passing None is treated as a programming error rather than an empty prefix. Pass an empty list [] if you want a definition with no PREFIX constraint.

Solutions

1. Pass an empty list for an unrestricted definition: IndexDefinition(prefix=[]).
2. Normalize None to [] at the call site before constructing IndexDefinition: prefix=prefix or [].
3. If a prefix is genuinely required, supply the real key prefix(es), e.g. prefix=['doc:'].

Example fix

// before
IndexDefinition(prefix=None)
// after
IndexDefinition(prefix=[])
// or
IndexDefinition(prefix=['doc:'])

prefix = prefix if prefix is not None else []
IndexDefinition(prefix=prefix)

def is_prefix_list(p) -> bool:
    return p is None or (isinstance(p, (list, tuple)) and all(isinstance(x, str) for x in p))

try:
    IndexDefinition(prefix=prefix)
except TypeError as e:
    if 'prefix must be provided' in str(e):
        prefix = prefix or []
    else:
        raise

When it happens

Trigger: Constructing IndexDefinition(prefix=None) (or omitting prefix after someone rebinds the default to None). The default is prefix=[], which is fine; only an explicit None triggers it.

Common situations: Calling code forwards an unset config value (e.g. from an env var or YAML that maps to None instead of []). Refactoring that drops the default. Code that treats None as 'not specified' across the whole IndexDefinition kwargs.

Related errors

• At least one tag must be specified
• 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.

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

Appendix: source

Thrown at redis/commands/search/index_definition.py:48

        self._append_prefix(prefix)
        self._append_filter(filter)
        self._append_language(language_field, language)
        self._append_score(score_field, score)
        self._append_payload(payload_field)

    def _append_index_type(self, index_type):
        """Append `ON HASH` or `ON JSON` according to the enum."""
        if index_type is IndexType.HASH:
            self.args.extend(["ON", "HASH"])
        elif index_type is IndexType.JSON:
            self.args.extend(["ON", "JSON"])
        elif index_type is not None:
            raise RuntimeError(f"index_type must be one of {list(IndexType)}")

    def _append_prefix(self, prefix):
        """Append PREFIX."""
        if prefix is None:
            raise TypeError("prefix must be provided")
        if len(prefix) > 0:
            prefix = list_or_args(prefix, [])
            self.args.append("PREFIX")
            self.args.append(len(prefix))
            for p in prefix:
                self.args.append(p)

    def _append_filter(self, filter):
        """Append FILTER."""
        if filter is not None:
            self.args.append("FILTER")
            self.args.append(filter)

    def _append_language(self, language_field, language):
        """Append LANGUAGE_FIELD and LANGUAGE."""
        if language_field is not None:
            self.args.append("LANGUAGE_FIELD")
            self.args.append(language_field)

View on GitHub (pinned to 6a6b581b48)