Input validation gaps: invalid ports, Optional[bool] form backfill, async error callback

[strawgate]

Three small input validation issues across different subsystems.

1. Settings accepts invalid port numbers (settings.py)

from fastmcp.settings import Settings
Settings(port=-1)    # accepted
Settings(port=99999) # accepted

No validation on the port field. Should reject ports outside 1-65535.

2. Form boolean backfill misses Optional[bool] (apps/form.py)

from fastmcp.apps.form import _backfill_boolean_defaults
import pydantic

class M(pydantic.BaseModel):
    flag: bool = False
    opt: bool | None = False

_backfill_boolean_defaults(M, {})  # returns {'flag': False} — 'opt' missing

Line 70 uses `field_info.annotation is bool` which doesn't match `bool | None`. Unchecked `Optional[bool]` checkboxes are missing from form data, causing Pydantic validation to fail.

3. ErrorHandlingMiddleware silently drops async error callbacks

async def my_callback(error, context):
    await log_to_service(error)  # never runs

mcp.add_middleware(ErrorHandlingMiddleware(error_callback=my_callback))

Line 77 of `error_handling.py` calls `self.error_callback(error, context)` without `await`. If the callback is async, the coroutine is created but never awaited — silently dropped with no warning.

Note: the type hint says `Callable[..., None]` (sync), but nothing prevents passing an async callable, and the silent failure is surprising.

[marvin-context-protocol]

Claude finished @strawgate's task in 1m 50s —— View job

---

tl;dr

All three bugs are real and confirmed locally. They are independent, small fixes in different subsystems. I recommend implementing all three in one PR (labeled bug) since the reporter framed them as one report and they share a theme (input validation gaps).

Recommendation

Fix all three:

1. port — constrain to 1..=65535 via Field(ge=1, le=65535) on settings.py:261.
2. _backfill_boolean_defaults — replace the is bool identity check with a check that also matches bool | None (and Optional[bool]) by unwrapping Union/Optional and looking for bool in the type args.
3. error_callback — support both sync and async callbacks. Detect a coroutine return from self.error_callback(...) and await it. Update the type hint to Callable[[Exception, MiddlewareContext], None | Awaitable[None]]. This requires making _log_error async (it is only called from the async on_message, so this is safe).

Findings

1. Port validation — src/fastmcp/settings.py:261 is a bare port: int = 8000 with no bounds. Verified:

port=-1: -1
port=99999: 99999
port=0: 0

2. Form boolean backfill — src/fastmcp/apps/form.py:70 uses field_info.annotation is bool. For opt: bool | None, annotation is the Union type, so identity fails. Verified with the issue's MRE:

Result: {'flag': False}   # 'opt' not backfilled

Existing tests at tests/apps/test_form.py:147-170 cover bool but not bool | None.

3. Async error callback — src/fastmcp/server/middleware/error_handling.py:77 calls self.error_callback(error, context) synchronously. If the callback is async, the coroutine is created and dropped. Verified:

RuntimeWarning: coroutine 'cb' was never awaited
Callback called: []

The existing tests (tests/server/middleware/test_error_handling.py:85-104) only use sync MagicMock callbacks, which is why this slipped through.

Verification

Installed uv, ran uv sync, and reproduced each bug with small repro scripts. All three reproduce exactly as described in the issue. The bugs are isolated to the three files cited — no hidden branches or indirection.

Detailed Action Plan

Step 1 — Port bounds (src/fastmcp/settings.py):

port: Annotated[int, Field(ge=1, le=65535)] = 8000

(Use the existing Annotated + Field pattern already used elsewhere in the file.) Add a test in tests/test_settings.py (or the nearest existing settings-tests file) asserting Settings(port=0), Settings(port=-1), and Settings(port=99999) each raise pydantic.ValidationError, and Settings(port=1) / Settings(port=65535) succeed.

Step 2 — Optional-bool backfill (src/fastmcp/apps/form.py):

Replace the is bool check with a helper that handles Union/Optional:

import typing

def _is_bool_annotation(annotation: Any) -> bool:
    if annotation is bool:
        return True
    origin = typing.get_origin(annotation)
    if origin is typing.Union or origin is types.UnionType:
        return any(arg is bool for arg in typing.get_args(annotation))
    return False

Then in _backfill_boolean_defaults, use _is_bool_annotation(field_info.annotation). Note: for a bool | None field with no default and no submission, backfilling False preserves current behavior for required bool; for bool | None fields that genuinely want None when unchecked, the field's own default (which the current code already honors via field_info.default) will win. Add tests in TestBackfillBooleanDefaults for:

• bool | None = False → backfills False
• bool | None = None → backfills None
• bool | None (no default) → backfills False (matches existing required-bool behavior)

Step 3 — Async error callback (src/fastmcp/server/middleware/error_handling.py):

1. Update the type annotation on __init__:

   error_callback: Callable[
       [Exception, MiddlewareContext], None | Awaitable[None]
   ] | None = None,

2. Make _log_error async (it's only called from the async on_message, so callers just need await):

   async def _log_error(self, error, context):
       ...
       if self.error_callback:
           try:
               result = self.error_callback(error, context)
               if inspect.isawaitable(result):
                   await result
           except Exception as callback_error:
               self.logger.error(f"Error in error callback: {callback_error}")

3. Update the single caller in on_message: await self._log_error(error, context).
4. Update the existing sync tests to await middleware._log_error(...) (mark tests async) and add a new test using an AsyncMock or plain async def callback that records calls and asserts it was awaited.

Step 4 — Run checks:

uv run pytest -n auto
uv run prek run --all-files

All three fixes are tiny. One PR, label bug. Title suggestion: "Fix three input validation gaps: port bounds, Optional[bool] backfill, async error callback".

Related Files

File	Lines	Relevance
src/fastmcp/settings.py	261	Port field with no bounds
src/fastmcp/apps/form.py	57–75	_backfill_boolean_defaults uses is bool identity check
src/fastmcp/server/middleware/error_handling.py	41, 75–79	Sync type hint + un-awaited callback call
tests/apps/test_form.py	147–170	Existing backfill tests — add Optional[bool] cases here
tests/server/middleware/test_error_handling.py	85–104	Existing callback tests — add async callback case

Todo

• Read issue and relevant source files
• Reproduce all three bugs locally
• Write up findings and action plan
  · branch claude/issue-3924-20260414-0406

---

Marvin Context Protocol | Type /marvin to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[strawgate]

Closing — on review, these are either type-checking issues (async callback with sync type hint), OS-level validation (port fails at bind time), or edge cases with minimal real-world impact (Optional[bool] form fields without defaults). Not worth the maintainer's time.