{"id":"548c2418183d3879","repo":"redis/redis-py","slug":"himport-fields-must-be-a-collection-of-field-names","errorCode":null,"errorMessage":"HIMPORT fields must be a collection of field names, not a single string or binary value","messagePattern":"HIMPORT fields must be a collection of field names, not a single string or binary value","errorType":"validation","errorClass":"DataError","httpStatus":null,"severity":"error","filePath":"redis/himport.py","lineNumber":242,"sourceCode":"\n    @staticmethod\n    def _materialize_fields(fields: Iterable[FieldT]) -> tuple:\n        \"\"\"Validate and materialize the caller's field iterable into a tuple.\n\n        Done *before* the mutation lock is taken: consuming an arbitrary iterable\n        can be slow, or -- for a generator that inspects this same registry -- can\n        re-enter a locked read (e.g. ``yield`` then ``registry.names()``). Running\n        it under the non-reentrant ``_lock`` would stall every registry user or\n        deadlock permanently. Field order is preserved; nothing is reordered or\n        deduplicated.\n        \"\"\"\n        # A bare single field name (str/bytes/bytearray/memoryview) is itself\n        # iterable element-by-element; that is almost certainly a caller mistake and\n        # would silently register single-character/single-byte \"fields\" (e.g.\n        # memoryview(b\"id\") -> field names 105, 100), so reject it as invalid local\n        # API usage. int/float are not iterable, so tuple() below rejects them.\n        if isinstance(fields, (str, bytes, bytearray, memoryview)):\n            raise DataError(\n                \"HIMPORT fields must be a collection of field names, \"\n                \"not a single string or binary value\"\n            )\n        field_tuple = tuple(fields)\n        if not field_tuple:\n            raise DataError(\"HIMPORT fieldset must have at least one field\")\n        return field_tuple\n\n    def _set(self, name: str, field_tuple: tuple) -> HImportFieldset:\n        # ``field_tuple`` is already validated/materialized by\n        # :meth:`_materialize_fields`; only the (cheap, non-blocking) revision bump\n        # and dict mutation run here, so ``_lock`` is never held across arbitrary\n        # caller code.\n        fieldset = HImportFieldset(\n            name=name,\n            fields=field_tuple,\n            version=self._advance(),\n        )","sourceCodeStart":224,"sourceCodeEnd":260,"githubUrl":"https://github.com/redis/redis-py/blob/da03cdc7e8731092b13e395605c3c1fb2de25de1/redis/himport.py#L224-L260","documentation":"Raised as redis.exceptions.DataError by HImportRegistry._materialize_fields (redis/himport.py:242). The HIMPORT fieldset must be a collection of field names; a bare str/bytes/bytearray/memoryview is itself iterable character-by-character and would silently register single-character 'fields' (e.g. memoryview(b'id') -> fields 105, 100). To prevent that footgun the registry rejects single scalar values up front.","triggerScenarios":"Calling registry.prepare(name, 'email') or client-side HIMPORT PREPARE with a single string instead of a list/tuple of field names.","commonSituations":"Forgetting to wrap a lone field name in a list; passing a bytes field name; confusing the single-name API with the field-collection API.","solutions":["Always pass a list/tuple of field names, even for one field: ['email'] not 'email'.","For bytes field names, wrap in a collection: [b'email'].","Add a helper that normalizes a single name into a one-element list at your call boundary."],"exampleFix":"// before\nregistry.prepare('account_data', 'email')\n\n// after\nregistry.prepare('account_data', ['email'])","handlingStrategy":"validation","validationCode":"from collections.abc import Iterable\nfrom typing import Union\n\ndef as_field_collection(fields):\n    if isinstance(fields, (str, bytes, bytearray, memoryview)):\n        return [fields]  # wrap a lone name\n    return list(fields)\n\nregistry.prepare('account_data', as_field_collection(fields_arg))","typeGuard":"from collections.abc import Iterable\n\ndef is_field_collection(v) -> bool:\n    return isinstance(v, Iterable) and not isinstance(v, (str, bytes, bytearray, memoryview))","tryCatchPattern":null,"preventionTips":["Always pass a list/tuple of field names, even for a single field.","Normalize single-name inputs into a one-element list at your call boundary.","Add a unit test that prepare() rejects a bare string, catching the regression."],"tags":["himport","dataerror","validation","fieldset"],"analyzedSha":"da03cdc7e8731092b13e395605c3c1fb2de25de1","analyzedAt":"2026-08-04T20:26:47.563Z","schemaVersion":2}