Pydantic PydanticSchemaGenerationError when using

The Fix

pip install pydantic==2.8.1

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

Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.

Jump to Verify Open PR/Commit

@@ -207,7 +207,15 @@ def path_schema_prepare_pydantic_annotations(
     import pathlib
 
-    if source_type not in {
+    orig_source_type: Any = get_origin(source_type) or source_type
+    if (

repro.py

# main.py

import os
import pydantic

class Model(pydantic.BaseModel):
    field: os.PathLike[str]

verify

Re-run: python main.py

fix.md

Option A — Upgrade to fixed release\npip install pydantic==2.8.1\nWhen NOT to use: Do not use if it changes public behavior or if the failure cannot be reproduced.\n\n

Why This Fix Works in Production

Trigger: $ python main.py
Mechanism: Fixes the issue with os.PathLike subtype handling in Pydantic, allowing for os.PathLike[str] and os.PathLike[bytes] to be used correctly.
Why the fix works: Fixes the issue with os.PathLike subtype handling in Pydantic, allowing for os.PathLike[str] and os.PathLike[bytes] to be used correctly. (first fixed release: 2.8.1).

Production impact:

If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.

Why This Breaks in Prod

Surfaces as: $ python main.py

Proof / Evidence

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

Discussion

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

Jump to Sources Open on GitHub

“I think os.PathLike[Any] should be supported as well. Omitting the generic notation equals Any, so os.PathLike is the same as os.PathLike[Any].”

@unicodestrangely · 2024-06-25 · source

“@nix010 Yes, it should raise an error. os.PathLike (even [Any]) must have an __fspath__ method (docs).”

@unicodestrangely · 2024-06-26 · source

“Indeed, looks like a bug! Help welcome here - should be fix in the _std_types_schema.py file.”

@sydney-runkle · 2024-06-20 · source

“@sydney-runkle so do we expect any certain behaviors that different from os.PathLike for the os.PathLike[str], os.PathLike[bytes] type ? And also what are the limit for…”

@nix010 · 2024-06-23 · source

Failure Signature (Search String)

$ python main.py

Error Message

Stack trace

error.txt

Error Message
-------------
$ python main.py 
Traceback (most recent call last):
  File "main.py", line 5, in <module>
    class Model(pydantic.BaseModel):
  File "pydantic/_internal/_model_construction.py", line 202, in __new__
    complete_model_class(
  File "pydantic/_internal/_model_construction.py", line 539, in complete_model_class
    schema = cls.__get_pydantic_core_schema__(cls, handler)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "pydantic/main.py", line 626, in __get_pydantic_core_schema__
    return handler(source)
           ^^^^^^^^^^^^^^^
  File "pydantic/_internal/_schema_generation_shared.py", line 82, in __call__
    schema = self._handler(source_type)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "pydantic/_internal/_generate_schema.py", line 502, in generate_schema
    schema = self._generate_schema_inner(obj)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "pydantic/_internal/_generate_schema.py", line 753, in _generate_schema_inner
    return self._model_schema(obj)
           ^^^^^^^^^^^^^^^^^^^^^^^
  File "pydantic/_internal/_generate_schema.py", line 580, in _model_schema
    {k: self._generate_md_field_schema(k, v, decorators) for k, v in fields.items()},
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "pydantic/_internal/_generate_schema.py", line 580, in <dictcomp>
    {k: self._generate_md_field_schema(k
... (truncated) ...

Minimal Reproduction

repro.py

# main.py

import os
import pydantic

class Model(pydantic.BaseModel):
    field: os.PathLike[str]

Environment

Pydantic: 2

Fix Options (Details)

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

pip install pydantic==2.8.1

When NOT to use: Do not use if it changes public behavior or if the failure cannot be reproduced.

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

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

First fixed release: 2.8.1

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

When NOT to Use This Fix

Do not use if it changes public behavior or if the failure cannot be reproduced.

Verify Fix

verify

Re-run: python main.py

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.8.1	Fixed

Related Issues

No related fixes found.

Cluster: pydantic:configuration-error Pydantic hub Pydantic best practices All hubs All clusters

Related clusters: Data consistency OpenAPI schema Serialization

Sources

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

Pydantic PydanticSchemaGenerationError when using os.PathLike[str] (Fix)