Python 3.14 Compatibility: fastmcp 2.10.6 incompatible with pydantic 2.12+

[jnorthrup]

Python 3.14 Compatibility: fastmcp 2.10.6 Incompatible with pydantic 2.12+

Summary

The project fails to run on Python 3.14 due to a compatibility issue between fastmcp 2.10.6 and pydantic 2.12+, which is required for Python 3.14 support.

Environment

• Python Version: 3.14.0 (Homebrew)
• Git Branch: develop
• Latest Commit: ea807ea - "fix: swe pro bench public url"
• Operating System: macOS (Darwin)
• Architecture: ARM64 (Apple Silicon)

Root Cause Analysis

Dependency Chain

ii-agent
├── fastmcp==2.10.6
│   └── pydantic[email]>=2.11.7  (constraint)
└── pydantic==2.12.4  (required for Python 3.14)
    └── pydantic-core==2.41.5

What Works

• ✅ pydantic-core 2.41.5 compiles successfully on Python 3.14 (uses PyO3 with Python 3.14 support)
• ✅ pydantic 2.12.4 installs and imports correctly
• ✅ All other dependencies resolve properly with uv sync

What Fails

• ❌ fastmcp 2.10.6 import fails with pydantic 2.12.4
• ❌ Error occurs in fastmcp.settings.Settings class definition
• ❌ Specific Issue: server_dependencies field uses both default_factory=list and = []

Error Details

from fastmcp import FastMCP

Traceback:

File "/Users/jim/work/ii-agent/.venv/lib/python3.14/site-packages/fastmcp/__init__.py", line 5, in <module>
  from fastmcp.settings import Settings
File "/Users/jim/work/ii-agent/.venv/lib/python3.14/site-packages/fastmcp/settings.py", line 58, in <module>
  class Settings(BaseSettings):
  ...<198 lines>...
        ] = None
  File "/Users/jim/work/ii-agent/.venv/lib/python3.14/site-packages/pydantic/_internal/_model_construction.py", line 242, in __new__
    set_model_fields(cls, config_wrapper=config_wrapper, ns_resolver=ns_resolver)
  File "/Users/jim/work/ii-agent/.venv/lib/python3.14/site-packages/pydantic/_internal/_model_construction.py", line 566, in set_model_fields
    fields, class_vars = collect_model_fields(cls, config_wrapper, ns_resolver, typevars_map=typevars_map)
  File "/Users/jim/work/ii-agent/.venv/lib/python3.14/site-packages/pydantic/_internal/_fields.py", line 363, in collect_model_fields
    field_info = FieldInfo_.from_annotated_attribute(ann_type, assigned_value, _source=AnnotationSource.CLASS)
  File "/Users/jim/work/ii-agent/.venv/lib/python3.14/site-packages/pydantic/fields.py", line 468, in from_annotated_attribute
    field_info = FieldInfo._construct(
        prepend_metadata + metadata if prepend_metadata is not None else metadata, **attr_overrides
    )
  File "/Users/jim/work/ii-agent/.venv/lib/python3.14/site-packages/pydantic/fields.py", line 563, in _construct
    merged_field_info = cls(**merged_kwargs)
  File "/Users/jim/work/ii-agent/.venv/lib/python3.14/site-packages/pydantic/fields.py", line 252, in __init__
    raise TypeError('cannot specify both default and default_factory')
TypeError: cannot specify both default and default_factory

The Real Issue

The error message reveals that fastmcp 2.10.6's code is incompatible with pydantic 2.12.x due to breaking changes in pydantic's Field API between versions 2.11 and 2.12.

Problem Code (fastmcp/settings.py line 199-205):

server_dependencies: Annotated[
    list[str],
    Field(
        default_factory=list,
        description="List of dependencies to install in the server environment",
    ),
] = []  # <-- PROBLEM: Cannot use both default_factory AND default value

In pydantic 2.12+, you cannot specify both default_factory in Field() AND assign a default value with =. You must choose one or the other.

• fastmcp's dependency: pydantic[email]>=2.11.7
• Python 3.14 requirement: pydantic==2.12.4 (or newer)
• Problem: fastmcp 2.10.6 code uses deprecated/removed pydantic APIs

Local Fix Applied

✅ Successfully patched locally by removing the = [] default assignment:

 server_dependencies: Annotated[
     list[str],
     Field(
         default_factory=list,
         description="List of dependencies to install in the server environment",
     ),
-] = []
+]  # Removed = [] to fix pydantic 2.12 compatibility

After applying this patch, fastmcp imports successfully on Python 3.14 with pydantic 2.12.4.

Workarounds Attempted

1. ✅ Compiled pydantic-core 2.41.5 successfully with PyO3 (works)
2. ✅ Used pydantic==2.12.4 (imports successfully)
3. ✅ PATCHED fastmcp - removed conflicting default value (works)
4. ❌ Cannot use pipx (conflicting dependency resolution)

Options to Resolve

Option 1: Update fastmcp (Recommended)

Request upstream fastmcp maintainers to release a version compatible with pydantic 2.12+:

• Fix Settings class to use pydantic 2.12+ Field API (remove = [] when using default_factory)
• Update dependency constraint to pydantic[email]>=2.12.0

Option 2: Downgrade to Python 3.13

Use Python 3.13 which supports:

• pydantic 2.11.7
• pydantic-core 2.33.2
• fastmcp 2.10.6 (current version) without patch

Option 3: Apply Local Patch

Apply the patch in the virtual environment:

# After uv sync, manually edit:
.venv/lib/python3.14/site-packages/fastmcp/settings.py
# Remove line 205: "] = []"

Option 4: Remove fastmcp/ii-tool Dependency

If ii-tool functionality is not critical:

• Remove fastmcp from dependencies
• Keep only ii-agent core

Current Status

• ✅ ii-agent core: Working with Python 3.14 + pydantic 2.12.4
• ✅ fastmcp (patched): Working after local patch
• ✅ ii-tool: Working with patched fastmcp
• ✅ Full environment: Ready in .venv/ (Python 3.14)

Verification Commands

$ python3 --version
Python 3.14.0

$ source .venv/bin/activate && uv pip list | grep -E "pydantic|fastmcp"
fastmcp               2.10.6
pydantic              2.12.4
pydantic-core         2.41.5
pydantic-settings     2.12.0

$ source .venv/bin/activate && python3 -c "import fastmcp; print('✅ fastmcp loads')"
✅ fastmcp loads

$ source .venv/bin/activate && python3 -c "from fastmcp import FastMCP; print('✅ FastMCP works')"
✅ FastMCP works

Recommendation

Short-term: Apply local patch or downgrade to Python 3.13
Long-term: Submit PR to fastmcp upstream to support pydantic 2.12+

Fix Details

The fix is simple and non-breaking:

# File: fastmcp/settings.py
# Line: 205
# Change: Remove "= []" after the closing bracket
# Reason: Field(default_factory=list) already provides default, cannot also use = []

This is a pydantic 2.12+ requirement - the Field API no longer allows specifying both default_factory and a default value.

Related Issues

• pydantic v2.12 Field API changes: https://docs.pydantic.dev/2.12/migration/
• Python 3.14 support requires pydantic-core compiled with PyO3 0.24+
• fastmcp issue: Code-level incompatibility, not dependency resolution issue