# Pitfall Log

Project: pydantic/pydantic-ai

Summary: Found 38 structured pitfall item(s), including 14 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_1ba1e19b3084422e8159cd03a471ff22 | https://github.com/pydantic/pydantic-ai/issues/530

## 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_33fbdccc2f504c9b8e403096036955b2 | https://github.com/pydantic/pydantic-ai/issues/4580

## 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_541e0749d4804613aefb3265ecdbffd3 | https://github.com/pydantic/pydantic-ai/issues/4773

## 4. 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_2fc34eb4512b462e8dae7f13caca7503 | https://github.com/pydantic/pydantic-ai/issues/5764

## 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_e96ced1f99cd4c5fa1d03d941a794046 | https://github.com/pydantic/pydantic-ai/issues/5755

## 6. 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_dc917318a7ca470d83f95ba2d1c75343 | https://github.com/pydantic/pydantic-ai/issues/5760

## 7. Runtime risk - Runtime risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_435f54efc7884881b6a2d5da81e14c64 | https://github.com/pydantic/pydantic-ai/issues/5160

## 8. 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_be644079d636479eb07771abb7e71b3f | https://github.com/pydantic/pydantic-ai/issues/5765

## 9. 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: Proposal: Gating tool execution with a policy/audit layer
- User impact: Developers may expose sensitive permissions or credentials: Proposal: Gating tool execution with a policy/audit layer
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Proposal: Gating tool execution with a policy/audit layer. Context: Source discussion did not expose a precise runtime context.
- Guardrail: Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/pydantic/pydantic-ai/issues/5730
- Evidence: failure_mode_cluster:github_issue | fmev_a90f4d42528dc6e6897fd66b928ca7f3 | https://github.com/pydantic/pydantic-ai/issues/5730

## 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_aa4ad5bf22b842c8858396f7ed4269af | https://github.com/pydantic/pydantic-ai/issues/5769

## 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_61823dcdcb09428da7bf968335da3cb6 | https://github.com/pydantic/pydantic-ai/issues/5770

## 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_19737eac52114aa19adaf7cac89b18e1 | https://github.com/pydantic/pydantic-ai/issues/5685

## 13. 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_a69792d39f034dada7823419788ed69b | https://github.com/pydantic/pydantic-ai/issues/5766

## 14. 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_87ff5149730c43c08be43f566eba53d5 | https://github.com/pydantic/pydantic-ai/issues/5662

## 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: Ability to Persist Messages in External Stores
- User impact: Developers may fail before the first successful local run: Ability to Persist Messages in External Stores
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Ability to Persist Messages in External Stores. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_54170f3a39ee83664ab7f6ce25002f60 | https://github.com/pydantic/pydantic-ai/issues/530, failure_mode_cluster:github_issue | fmev_698b4104d1eaaf335db04bb533f60f5a | https://github.com/pydantic/pydantic-ai/issues/530

## 16. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Feature request: Structured inter-agent message passing for multi-agent workflows
- User impact: Developers may misconfigure credentials, environment, or host setup: Feature request: Structured inter-agent message passing for multi-agent workflows
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Feature request: Structured inter-agent message passing for multi-agent workflows. Context: Observed when using node, python
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_deac22e10cf1fff5200cfd245561d3f7 | https://github.com/pydantic/pydantic-ai/issues/4580

## 17. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: GoogleModel returns empty responses (0 tokens) after v1.92.0 streaming cleanup changes (PR #5313)
- User impact: Developers may misconfigure credentials, environment, or host setup: GoogleModel returns empty responses (0 tokens) after v1.92.0 streaming cleanup changes (PR #5313)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: GoogleModel returns empty responses (0 tokens) after v1.92.0 streaming cleanup changes (PR #5313). Context: Observed when using python
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_9b58ca15ac6c4cf63280c79ce27f8a9c | https://github.com/pydantic/pydantic-ai/issues/5769

## 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: [aw] No-Op Runs
- User impact: Developers may misconfigure credentials, environment, or host setup: [aw] No-Op Runs
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [aw] No-Op Runs. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_20b477b411d64dd916c420008517657f | https://github.com/pydantic/pydantic-ai/issues/5685

## 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: [aw] Pydantic AI Regression Detector failed
- User impact: Developers may misconfigure credentials, environment, or host setup: [aw] Pydantic AI Regression Detector failed
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [aw] Pydantic AI Regression Detector failed. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_83bc7d75e9c6b1abee00f7d97484539e | https://github.com/pydantic/pydantic-ai/issues/5766

## 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: [roundtrip-sweep] Vercel AI & AG-UI adapters: FileUrl.vendor_metadata and BinaryContent.vendor_metadata silently dropped on round-trip (UploadedFi [Content truncated due to length]
- User impact: Developers may misconfigure credentials, environment, or host setup: [roundtrip-sweep] Vercel AI & AG-UI adapters: FileUrl.vendor_metadata and BinaryContent.vendor_metadata silently dropped on round-trip (UploadedFi [Content truncated due to length]
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [roundtrip-sweep] Vercel AI & AG-UI adapters: FileUrl.vendor_metadata and BinaryContent.vendor_metadata silently dropped on round-trip (UploadedFi [Content truncated due to length]. Context: Observed when using python
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_41bbc23fb60ddb228c089e07f6d4c056 | https://github.com/pydantic/pydantic-ai/issues/5764

## 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: v1.105.0 (2026-06-02)
- User impact: Upgrade or migration may change expected behavior: v1.105.0 (2026-06-02)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v1.105.0 (2026-06-02). Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_05352904ff5112f3966bf29f71dfaeda | https://github.com/pydantic/pydantic-ai/releases/tag/v1.105.0

## 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: v2.0.0b4 (2026-05-28)
- User impact: Upgrade or migration may change expected behavior: v2.0.0b4 (2026-05-28)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v2.0.0b4 (2026-05-28). Context: Observed during version upgrade or migration.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_ae5f298d763108673d171145441c291e | https://github.com/pydantic/pydantic-ai/releases/tag/v2.0.0b4

## 23. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v2.0.0b5 (2026-06-02)
- User impact: Upgrade or migration may change expected behavior: v2.0.0b5 (2026-06-02)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v2.0.0b5 (2026-06-02). Context: Observed during version upgrade or migration.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_89506d92e0852002a12ee4beb919a873 | https://github.com/pydantic/pydantic-ai/releases/tag/v2.0.0b5

## 24. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: xAI: review support for newer SDK request and provider options
- User impact: Developers may misconfigure credentials, environment, or host setup: xAI: review support for newer SDK request and provider options
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: xAI: review support for newer SDK request and provider options. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_2469771c2a6656a9189684b6fa9f4adf | https://github.com/pydantic/pydantic-ai/issues/5662

## 25. Configuration risk - Configuration risk requires verification

- Severity: medium
- 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_f0ed5e9f990e4f1798ca72dcd5bac357 | https://github.com/pydantic/pydantic-ai/issues/4773

## 26. Configuration risk - Configuration risk requires verification

- Severity: medium
- 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_fb7d0e6807594ce6a95a4f9892f6524e | https://github.com/pydantic/pydantic-ai/issues/5676

## 27. 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.assumptions | github_repo:818331198 | https://github.com/pydantic/pydantic-ai

## 28. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this migration risk before relying on the project: [aw] Pydantic AI Stale Issues Finder failed
- User impact: Developers may hit a documented source-backed failure mode: [aw] Pydantic AI Stale Issues Finder failed
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [aw] Pydantic AI Stale Issues Finder failed. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_202f15e7f8814be6c7f23ddeb7c36c55 | https://github.com/pydantic/pydantic-ai/issues/5676

## 29. 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:818331198 | https://github.com/pydantic/pydantic-ai

## 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: downstream_validation.risk_items | github_repo:818331198 | https://github.com/pydantic/pydantic-ai

## 31. 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: risks.scoring_risks | github_repo:818331198 | https://github.com/pydantic/pydantic-ai

## 32. 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_4a78d04c196144ecaf216267b5236a0d | https://github.com/pydantic/pydantic-ai/issues/5730

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

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: Feature request: Structured inter-agent message passing for multi-agent workflows
- User impact: Developers may hit a documented source-backed failure mode: Feature request: Structured inter-agent message passing for multi-agent workflows
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Feature request: Structured inter-agent message passing for multi-agent workflows. Context: Observed when using node, python
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_5206f56a00fde74ea466c266c3622be9 | https://github.com/pydantic/pydantic-ai/issues/4580

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

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: [aw] Pydantic AI Round-Trip Sweep failed
- User impact: Developers may hit a documented source-backed failure mode: [aw] Pydantic AI Round-Trip Sweep failed
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [aw] Pydantic AI Round-Trip Sweep failed. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_fefeae2c6d1d7bfece08ff2fde309368 | https://github.com/pydantic/pydantic-ai/issues/5755, failure_mode_cluster:github_issue | fmev_d5314d01a5e145b9f064347d9281d0c8 | https://github.com/pydantic/pydantic-ai/issues/5755

## 35. Runtime risk - Runtime risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: Gateway: Adaptive routing — latency-aware provider selection
- User impact: Developers may hit a documented source-backed failure mode: Gateway: Adaptive routing — latency-aware provider selection
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Gateway: Adaptive routing — latency-aware provider selection. Context: Observed during installation or first-run setup.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_bd6bcd74b3a1c5a6ba5746b31310c14e | https://github.com/pydantic/pydantic-ai/issues/5160

## 36. Runtime risk - Runtime risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: RFC: Pluggable cross-run memory layer (AbstractMemoryStore)
- User impact: Developers may hit a documented source-backed failure mode: RFC: Pluggable cross-run memory layer (AbstractMemoryStore)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: RFC: Pluggable cross-run memory layer (AbstractMemoryStore). Context: Observed when using python
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_da81ee4b210b17ee7c9172bc8d879aba | https://github.com/pydantic/pydantic-ai/issues/4773, failure_mode_cluster:github_issue | fmev_a165e27418d554855d292bd613db4257 | https://github.com/pydantic/pydantic-ai/issues/4773

## 37. 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:818331198 | https://github.com/pydantic/pydantic-ai

## 38. 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:818331198 | https://github.com/pydantic/pydantic-ai