{"id":"2d1af8d0bf0b2664","repo":"sqlalchemy/sqlalchemy","slug":"the-psycopg2-dialect-does-not-implement-ipaddress","errorCode":null,"errorMessage":"The psycopg2 dialect does not implement ipaddress type handling; native_inet_types cannot be set to ``True`` when using this dialect.","messagePattern":"The psycopg2 dialect does not implement ipaddress type handling; native_inet_types cannot be set to ``True`` when using this dialect\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"lib/sqlalchemy/dialects/postgresql/psycopg2.py","lineNumber":647,"sourceCode":"            ranges.INT4RANGE: _Psycopg2NumericRange,\n            ranges.INT8RANGE: _Psycopg2NumericRange,\n            ranges.NUMRANGE: _Psycopg2NumericRange,\n            ranges.DATERANGE: _Psycopg2DateRange,\n            ranges.TSRANGE: _Psycopg2DateTimeRange,\n            ranges.TSTZRANGE: _Psycopg2DateTimeTZRange,\n        },\n    )\n\n    def __init__(\n        self,\n        executemany_mode=\"values_only\",\n        executemany_batch_page_size=100,\n        **kwargs,\n    ):\n        _PGDialect_common_psycopg.__init__(self, **kwargs)\n\n        if self._native_inet_types:\n            raise NotImplementedError(\n                \"The psycopg2 dialect does not implement \"\n                \"ipaddress type handling; native_inet_types cannot be set \"\n                \"to ``True`` when using this dialect.\"\n            )\n\n        # Parse executemany_mode argument, allowing it to be only one of the\n        # symbol names\n        self.executemany_mode = parse_user_argument_for_enum(\n            executemany_mode,\n            {\n                EXECUTEMANY_VALUES: [\"values_only\"],\n                EXECUTEMANY_VALUES_PLUS_BATCH: [\"values_plus_batch\"],\n            },\n            \"executemany_mode\",\n        )\n\n        self.executemany_batch_page_size = executemany_batch_page_size\n","sourceCodeStart":629,"sourceCodeEnd":665,"githubUrl":"https://github.com/sqlalchemy/sqlalchemy/blob/d9b44cb731bd27e6e82c99a3c0fb598214e8e7ff/lib/sqlalchemy/dialects/postgresql/psycopg2.py#L629-L665","documentation":"Raised by the psycopg2 PostgreSQL dialect's __init__ when its inherited _native_inet_types flag is True. Unlike the psycopg (v3) dialect, psycopg2 does not implement native DBAPI-level handling for PostgreSQL inet/cidr/macaddr types, so it cannot honor that flag and refuses to initialize. The check exists because the flag is defined on the shared _PGDialect_common_psycopg base and would otherwise silently be ignored. SQLAlchemy throws NotImplementedError (a clear, fail-fast signal) rather than silently degrading behavior.","triggerScenarios":"Instantiating create_engine(\"postgresql+psycopg2://...\") while explicitly passing connect_args or dialect kwargs that set native_inet_types=True, or subclassing PGDialect_psycopg2 and overriding _native_inet_types. Also occurs if configuration meant for the psycopg (v3) dialect is copy-pasted onto a psycopg2 URL.","commonSituations":"Developers migrating from the newer psycopg (v3) driver to psycopg2 (or vice versa) and reusing the same engine kwargs. Config files or shared factory functions that set native_inet_types globally. Tutorials/examples written for psycopg3 being applied to a psycopg2-based project.","solutions":["Remove native_inet_types=True from your psycopg2 dialect kwargs/connect_args; the psycopg2 dialect handles inet types via Python-side processing instead.","If you need native inet handling, switch the driver to psycopg v3 by using the postgresql+psycopg:// URL (SQLAlchemy 2.0+) where native_inet_types is supported.","Audit shared engine-creation helpers to ensure native_inet_types is only applied conditionally based on the active dialect."],"exampleFix":"// before\nengine = create_engine(\n    \"postgresql+psycopg2://user:pass@host/db\",\n    connect_args={\"native_inet_types\": True},\n)\n\n// after\nengine = create_engine(\"postgresql+psycopg2://user:pass@host/db\")\n# or, switch to psycopg v3 for native inet handling:\nengine = create_engine(\n    \"postgresql+psycopg://user:pass@host/db\",\n    connect_args={\"native_inet_types\": True},\n)","handlingStrategy":"validation","validationCode":"dialect_url = \"postgresql+psycopg2://...\"\nnative_inet_types = True  # whatever you intended\nif dialect_url.startswith(\"postgresql+psycopg2\") and native_inet_types:\n    raise ValueError(\n        \"native_inet_types=True is unsupported on the psycopg2 dialect; \"\n        \"use the psycopg (v3) dialect 'postgresql+psycopg' instead.\"\n    )\n# then: create_engine(\"postgresql+psycopg://...\", native_inet_types=True)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never pass native_inet_types=True to the psycopg2 dialect; only the psycopg (v3) dialect implements ipaddress handling.","Use the 'postgresql+psycopg' URL scheme (the 'psycopg' package, not 'psycopg2') when you need native inet/IPAddress types.","Search your create_engine() / URL construction code for 'native_inet_types' and verify the dialect name whenever you enable it."],"tags":["sqlalchemy","psycopg2","postgresql","configuration","dialect"],"analyzedSha":"d9b44cb731bd27e6e82c99a3c0fb598214e8e7ff","analyzedAt":"2026-08-01T17:20:52.075Z","schemaVersion":2}