Pydantic PydanticSerializationError on IPv4Network

The Fix

pip install pydantic==2.4.1

Based on closed pydantic/pydantic issue #9957 · PR/commit linked

Jump to Verify Open PR/Commit

@@ -33,7 +33,7 @@
 from warnings import warn
 
-from pydantic_core import CoreSchema, PydanticUndefined, core_schema
+from pydantic_core import CoreSchema, PydanticUndefined, core_schema, to_jsonable_python
 from typing_extensions import Annotated, Final, Literal, TypeAliasType, TypedDict, get_args, get_origin, is_typeddict

repro.py

from fastapi import FastAPI
from ipaddress import IPv4Network
from pydantic import BaseModel, conint
from typing import List

app = FastAPI()

class PrefixListEntry(BaseModel):
    prefix: IPv4Network
    ge: conint(ge=1, le=32) | None = None
    le: conint(ge=1, le=32) | None = None

class PrefixListAdd(BaseModel):
    name: str
    entries: List[PrefixListEntry]

    class Config:
        schema_extra = {
            'example': {
                'name': 'my-prefixlist',
                 'entries': [
                     PrefixListEntry(prefix='10.0.1.1'),
                     PrefixListEntry(prefix='10.0.2.0/24', ge=26, le=31)
                 ] 
            }
        }

@app.post('/prefixlist')
def post_entry(entry: PrefixListAdd):
    pass

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

fix.md

Option A — Upgrade to fixed release\npip install pydantic==2.4.1\nWhen NOT to use: This fix should not be applied if using a version of Pydantic prior to V2.\n\n

Why This Fix Works in Production

Trigger: ERROR: Exception in ASGI application
Mechanism: The JSON schema extras were not JSON encoded in Pydantic V2, causing serialization issues
Why the fix works: Fixes an issue where JSON schema extras weren't JSON encoded, restoring intended behavior. (first fixed release: 2.4.1).

Production impact:

If left unfixed, this can cause silent data inconsistencies that propagate (bad cache entries, incorrect downstream decisions).

Why This Breaks in Prod

Shows up under Python 3.10 in real deployments (not just unit tests).
The JSON schema extras were not JSON encoded in Pydantic V2, causing serialization issues
Surfaces as: INFO: 127.0.0.1:46822 - "GET /openapi.json HTTP/1.1" 500 Internal Server Error

Proof / Evidence

GitHub issue: #9957
Fix PR: https://github.com/pydantic/pydantic/pull/7625
First fixed release: 2.4.1
Reproduced locally: No (not executed)
Last verified: 2026-02-09
Confidence: 0.85
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.33

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“@angely-dev, Are you able to come up with a purely pydantic MRE? The following reduced example seems to be working alright:”

@sydney-runkle · 2024-07-24 · source

“See https://github.com/tiangolo/fastapi/discussions/11885 hoping this won't be ignored.”

@angely-dev · 2024-07-26 · source

“I am not able to come up with a purely pydantic MRE”

@angely-dev · 2024-07-25 · source

Failure Signature (Search String)

ERROR: Exception in ASGI application

Error Message

Stack trace

error.txt

Error Message
-------------
INFO:     127.0.0.1:46822 - "GET /openapi.json HTTP/1.1" 500 Internal Server Error
ERROR:    Exception in ASGI application
Traceback (most recent call last):
  File "/tmp/wksp/venv/lib/python3.10/site-packages/uvicorn/protocols/http/httptools_impl.py", line 399, in run_asgi
    result = await app(  # type: ignore[func-returns-value]
  File "/tmp/wksp/venv/lib/python3.10/site-packages/uvicorn/middleware/proxy_headers.py", line 70, in __call__
    return await self.app(scope, receive, send)
  File "/tmp/wksp/venv/lib/python3.10/site-packages/fastapi/applications.py", line 1054, in __call__
    await super().__call__(scope, receive, send)
  File "/tmp/wksp/venv/lib/python3.10/site-packages/starlette/applications.py", line 123, in __call__
    await self.middleware_stack(scope, receive, send)
  File "/tmp/wksp/venv/lib/python3.10/site-packages/starlette/middleware/errors.py", line 186, in __call__
    raise exc
  File "/tmp/wksp/venv/lib/python3.10/site-packages/starlette/middleware/errors.py", line 164, in __call__
    await self.app(scope, receive, _send)
  File "/tmp/wksp/venv/lib/python3.10/site-packages/starlette/middleware/exceptions.py", line 65, in __call__
    await wrap_app_handling_exceptions(self.app, conn)(scope, receive, send)
  File "/tmp/wksp/venv/lib/python3.10/site-packages/starlette/_exception_handler.py", line 64, in wrapped_app
    raise exc
  File "/tmp/wksp/v
... (truncated) ...

Minimal Reproduction

repro.py

from fastapi import FastAPI
from ipaddress import IPv4Network
from pydantic import BaseModel, conint
from typing import List

app = FastAPI()

class PrefixListEntry(BaseModel):
    prefix: IPv4Network
    ge: conint(ge=1, le=32) | None = None
    le: conint(ge=1, le=32) | None = None

class PrefixListAdd(BaseModel):
    name: str
    entries: List[PrefixListEntry]

    class Config:
        schema_extra = {
            'example': {
                'name': 'my-prefixlist',
                 'entries': [
                     PrefixListEntry(prefix='10.0.1.1'),
                     PrefixListEntry(prefix='10.0.2.0/24', ge=26, le=31)
                 ] 
            }
        }

@app.post('/prefixlist')
def post_entry(entry: PrefixListAdd):
    pass

Environment

Python: 3.10
Pydantic: 2

What Broke

FastAPI fails to generate the OpenAPI schema, leading to potential API documentation issues.

Why It Broke

The JSON schema extras were not JSON encoded in Pydantic V2, causing serialization issues

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

pip install pydantic==2.4.1

When NOT to use: This fix should not be applied if using a version of Pydantic prior to V2.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

Option D — Guard side-effects with OnceOnly Guardrail for side-effects

Mitigate duplicate external side-effects under retries/timeouts/agent loops by gating the operation before calling external systems.

Place OnceOnly between your code/agent and real side-effects (Stripe, emails, CRM, APIs).
Use a stable key per side-effect (e.g., customer_id + action + idempotency_key).
Fail-safe: configure fail-open vs fail-closed based on blast radius and spend risk.
This does NOT fix data corruption; it only prevents duplicate side-effects.

Show example snippet (optional)

onceonly.py

from onceonly import OnceOnly
import os

once = OnceOnly(api_key=os.environ["ONCEONLY_API_KEY"], fail_open=True)

# Stable idempotency key per real side-effect.
# Use a request id / job id / webhook delivery id / Stripe event id, etc.
event_id = "evt_..."  # replace
key = f"stripe:webhook:{event_id}"

res = once.check_lock(key=key, ttl=3600)
if res.duplicate:
    return {"status": "already_processed"}

# Safe to execute the side-effect exactly once.
handle_event(event_id)

See OnceOnly SDK

When NOT to use: Do not use this to hide logic bugs or data corruption. Use it to block duplicate external side-effects and enforce tool permissions/spend caps.

Fix reference: https://github.com/pydantic/pydantic/pull/7625

First fixed release: 2.4.1

Last verified: 2026-02-09. Validate in your environment.

When NOT to Use This Fix

This fix should not be applied if using a version of Pydantic prior to V2.
Do not use this to hide logic bugs or data corruption. Use it to block duplicate external side-effects and enforce tool permissions/spend caps.

Verify Fix

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Add a CI check that diffs key outputs after upgrades (OpenAPI schema snapshots, JSON payload shapes, CLI output).
Upgrade behind a canary and run integration tests against the canary before 100% rollout.

Version Compatibility Table

Version	Status
2.4.1	Fixed

Related Issues

No related fixes found.

Cluster: pydantic:data-consistency Pydantic hub Pydantic best practices All hubs All clusters

Related clusters: Configuration error OpenAPI schema Serialization

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.

Pydantic PydanticSerializationError on IPv4Network (Standard Library Type) (Fix)