# Pitfall Log

Project: PrefectHQ/fastmcp

Summary: Found 33 structured pitfall item(s), including 12 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4306

## 2. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4241

## 3. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4300

## 4. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4321

## 5. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4305

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4326

## 7. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Developers should check this security_permissions risk before relying on the project: No guardrails against destructive tool capabilities (shell exec, file deletion, env access)
- User impact: Developers may expose sensitive permissions or credentials: No guardrails against destructive tool capabilities (shell exec, file deletion, env access)
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4318

## 8. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Developers should check this security_permissions risk before relying on the project: on_message middleware not called for unauthenticated requests
- User impact: Developers may expose sensitive permissions or credentials: on_message middleware not called for unauthenticated requests
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4309

## 9. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4318

## 10. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4320

## 11. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4304

## 12. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/4309

## 13. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Upgrade checks failing on main branch
- User impact: Developers may fail before the first successful local run: Upgrade checks failing on main branch
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4241

## 14. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: caching middleware broken
- User impact: Developers may fail before the first successful local run: caching middleware broken
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4300

## 15. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v3.3.1: Loop There It Is
- User impact: Upgrade or migration may change expected behavior: v3.3.1: Loop There It Is
- Evidence: failure_mode_cluster:github_release | https://github.com/PrefectHQ/fastmcp/releases/tag/v3.3.1

## 16. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v3.4.0: Remote Control
- User impact: Upgrade or migration may change expected behavior: v3.4.0: Remote Control
- Evidence: failure_mode_cluster:github_release | https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.0

## 17. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v3.4.1: Floor It
- User impact: Upgrade or migration may change expected behavior: v3.4.1: Floor It
- Evidence: failure_mode_cluster:github_release | https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.1

## 18. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: CIMD redirect_uri validation rejects loopback URIs with dynamic ports (RFC 8252 §7.3)
- User impact: Developers may misconfigure credentials, environment, or host setup: CIMD redirect_uri validation rejects loopback URIs with dynamic ports (RFC 8252 §7.3)
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/3588

## 19. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: feat: FastMCP(default_tool_timeout=...) for server-wide tool timeout default
- User impact: Developers may misconfigure credentials, environment, or host setup: feat: FastMCP(default_tool_timeout=...) for server-wide tool timeout default
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4304

## 20. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: feat: hook or factory for customizing tool timeout error messages and types
- User impact: Developers may misconfigure credentials, environment, or host setup: feat: hook or factory for customizing tool timeout error messages and types
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4305

## 21. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v3.4.0b1: Remote Possibility
- User impact: Upgrade or migration may change expected behavior: v3.4.0b1: Remote Possibility
- Evidence: failure_mode_cluster:github_release | https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.0b1

## 22. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v3.4.2: Heads Up
- User impact: Upgrade or migration may change expected behavior: v3.4.2: Heads Up
- Evidence: failure_mode_cluster:github_release | https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.2

## 23. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/PrefectHQ/fastmcp

## 24. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: FastMCP StatefulProxyClient.clear() can cause KeyError during proxy session teardown
- User impact: Developers may hit a documented source-backed failure mode: FastMCP StatefulProxyClient.clear() can cause KeyError during proxy session teardown
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4321

## 25. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: RateLimitingMiddleware.get_client_id passing an async callable silently disables rate limiting
- User impact: Developers may hit a documented source-backed failure mode: RateLimitingMiddleware.get_client_id passing an async callable silently disables rate limiting
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4320

## 26. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: RecursionError in json_schema_to_type on self-referential $ref in tool outputSchema
- User impact: Developers may hit a documented source-backed failure mode: RecursionError in json_schema_to_type on self-referential $ref in tool outputSchema
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4306

## 27. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this migration risk before relying on the project: expand_uri_template and match_uri_template do not round-trip path values containing reserved characters
- User impact: Developers may hit a documented source-backed failure mode: expand_uri_template and match_uri_template do not round-trip path values containing reserved characters
- Evidence: failure_mode_cluster:github_issue | https://github.com/PrefectHQ/fastmcp/issues/4326

## 28. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/PrefectHQ/fastmcp

## 29. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/PrefectHQ/fastmcp

## 30. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/PrefectHQ/fastmcp

## 31. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/PrefectHQ/fastmcp/issues/3588

## 32. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/PrefectHQ/fastmcp

## 33. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/PrefectHQ/fastmcp