Fix unhandled exceptions in OpenAPI POST tool calls

[jlowin]

OpenAPITool.run() only catches httpx.* exceptions, so any failure during request building (parameter routing, body construction) escapes unhandled and surfaces to clients as a generic "Internal Server Error" with no diagnostic info. This particularly affects POST requests where the body construction code exercises more fragile paths.

Two changes: harden _unflatten_arguments() to guard against empty content_schema dicts and non-dict body schemas, and add a catch-all in run() that wraps unexpected errors with the tool's method, path, and original error — so users see something like "Error building request for POST /items: KeyError: missing_param" instead of a silent 500.

mcp = FastMCP.from_openapi(openapi_spec=spec, client=client)
# POST tool calls that previously failed with "Internal Server Error"
# now produce actionable error messages

Closes #3113

[coderabbitai]

Walkthrough

Documentation anchors were updated to reflect new source line numbers. In src/fastmcp/server/providers/openapi/components.py, OpenAPITool.run now wraps request construction in a try/except and raises a ValueError containing HTTP method, path, exception type, and message if construction fails; the subsequent request send/response handling remains separate. In src/fastmcp/utilities/openapi/director.py, request-body construction now checks that route.request_body.content_schema exists and is non-empty and that the resolved body schema is a dict before accessing its "type" property.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: fixing unhandled exceptions in OpenAPI POST tool calls, which matches the core objective of improving error handling.
Description check	✅ Passed	The description comprehensively covers the changes, explains the problem (unhandled exceptions in request building), describes both code changes with examples, and explicitly links to the related issue #3113.
Linked Issues check	✅ Passed	The PR addresses issue #3113 by adding try/except exception handling in OpenAPITool.run() and defensive checks in _unflatten_arguments() to catch errors during request building and provide actionable error messages instead of generic 500 responses.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing exception handling in OpenAPI request building: exception handling in components.py, defensive schema checks in director.py, and documentation anchor updates. No unrelated changes detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/openapi-post-error-handling

---

No actionable comments were generated in the recent review. 🎉

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[jlowin]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bd3c3ccf4e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Limit catch-all to request-building failures

The new except Exception in OpenAPITool.run catches non-HTTPX errors from the entire method, not just request construction, so failures that happen after send() (for example response parsing or ToolResult validation) are now rethrown as Error building request ..., which is misleading and makes production debugging harder. Please scope this handler to the build step or use a message that matches all covered phases.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Remove edits under auto-generated python-sdk docs

This change modifies docs/python-sdk/**, but the repository guideline in /workspace/fastmcp/AGENTS.md states "Never modify docs/python-sdk/** (auto-generated)." Committing these generated line-reference updates creates avoidable churn and risks stale docs diffs being overwritten by generation tooling.

Useful? React with 👍 / 👎.

[sandeepkunusoth]

hi @jlowin how can i test this change with 2.14. version can this be released in 2.14.6?

[jlowin]

This went out in 3.0 rc1