sqlalchemy/sqlalchemy · error · NotImplementedError

The psycopg2 dialect does not implement ipaddress type handl

Error message

The psycopg2 dialect does not implement ipaddress type handling; native_inet_types cannot be set to ``True`` when using this dialect.

What it means

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.

Source

Thrown at lib/sqlalchemy/dialects/postgresql/psycopg2.py:647

            ranges.INT4RANGE: _Psycopg2NumericRange,
            ranges.INT8RANGE: _Psycopg2NumericRange,
            ranges.NUMRANGE: _Psycopg2NumericRange,
            ranges.DATERANGE: _Psycopg2DateRange,
            ranges.TSRANGE: _Psycopg2DateTimeRange,
            ranges.TSTZRANGE: _Psycopg2DateTimeTZRange,
        },
    )

    def __init__(
        self,
        executemany_mode="values_only",
        executemany_batch_page_size=100,
        **kwargs,
    ):
        _PGDialect_common_psycopg.__init__(self, **kwargs)

        if self._native_inet_types:
            raise NotImplementedError(
                "The psycopg2 dialect does not implement "
                "ipaddress type handling; native_inet_types cannot be set "
                "to ``True`` when using this dialect."
            )

        # Parse executemany_mode argument, allowing it to be only one of the
        # symbol names
        self.executemany_mode = parse_user_argument_for_enum(
            executemany_mode,
            {
                EXECUTEMANY_VALUES: ["values_only"],
                EXECUTEMANY_VALUES_PLUS_BATCH: ["values_plus_batch"],
            },
            "executemany_mode",
        )

        self.executemany_batch_page_size = executemany_batch_page_size

View on GitHub (pinned to d9b44cb731)

Solutions

1. Remove native_inet_types=True from your psycopg2 dialect kwargs/connect_args; the psycopg2 dialect handles inet types via Python-side processing instead.
2. 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.
3. Audit shared engine-creation helpers to ensure native_inet_types is only applied conditionally based on the active dialect.

Example fix

// before
engine = create_engine(
    "postgresql+psycopg2://user:pass@host/db",
    connect_args={"native_inet_types": True},
)

// after
engine = create_engine("postgresql+psycopg2://user:pass@host/db")
# or, switch to psycopg v3 for native inet handling:
engine = create_engine(
    "postgresql+psycopg://user:pass@host/db",
    connect_args={"native_inet_types": True},
)

dialect_url = "postgresql+psycopg2://..."
native_inet_types = True  # whatever you intended
if dialect_url.startswith("postgresql+psycopg2") and native_inet_types:
    raise ValueError(
        "native_inet_types=True is unsupported on the psycopg2 dialect; "
        "use the psycopg (v3) dialect 'postgresql+psycopg' instead."
    )
# then: create_engine("postgresql+psycopg://...", native_inet_types=True)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• psycopg2 version 2.7 or higher is required.
• The ping feature requires that a dialect is passed to the co
• could not parse %r as a date value
• could not parse %r as a time value
• length must be None or 'max' when setting filestream

AI-assisted analysis of sqlalchemy/sqlalchemy@d9b44cb731 (2026-08-01). Data as JSON: /data/errors/2d1af8d0bf0b2664.json. Report an issue: GitHub.