# Pitfall Log

Project: qdrant/fastembed

Summary: Found 29 potential pitfall items; 3 are high/blocking. Highest priority: installation - 来源证据：[Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2.

## 1. installation · 来源证据：[Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2

- Severity: high
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_201d4035515846df8830ca0dad6960c5 | https://github.com/qdrant/fastembed/issues/618 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. installation · 来源证据：[Bug]: Unable to load 'Qdrant/bm25' on macOS python3.14

- Severity: high
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Unable to load 'Qdrant/bm25' on macOS python3.14
- User impact: 可能阻塞安装或首次运行。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_8147621574b345d7955e79ad98f4ba6f | https://github.com/qdrant/fastembed/issues/630 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. security_permissions · 失败模式：security_permissions: [Bug]: Tar path traversal (Zip Slip) in decompress_to_cache — arbitrary file write outside ca...

- Severity: high
- Evidence strength: source_linked
- Finding: Developers should check this security_permissions risk before relying on the project: [Bug]: Tar path traversal (Zip Slip) in decompress_to_cache — arbitrary file write outside cache directory
- User impact: Developers may expose sensitive permissions or credentials: [Bug]: Tar path traversal (Zip Slip) in decompress_to_cache — arbitrary file write outside cache directory
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Tar path traversal (Zip Slip) in decompress_to_cache — arbitrary file write outside cache directory. Context: Observed when using python
- Guardrail action: Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/qdrant/fastembed/issues/626
- Evidence: failure_mode_cluster:github_issue | fmev_d3890c2b3360ccb937839f70fd4aa584 | https://github.com/qdrant/fastembed/issues/626 | [Bug]: Tar path traversal (Zip Slip) in decompress_to_cache — arbitrary file write outside cache directory

## 4. installation · 失败模式：installation: The dependency `py-rust-stemmers` cannot be downloaded in a pure Python environment.

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: The dependency `py-rust-stemmers` cannot be downloaded in a pure Python environment.
- User impact: Developers may fail before the first successful local run: The dependency `py-rust-stemmers` cannot be downloaded in a pure Python environment.
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: The dependency `py-rust-stemmers` cannot be downloaded in a pure Python environment.. Context: Observed when using python, docker
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_16e50a8626aff1576adeb1c0baab4785 | https://github.com/qdrant/fastembed/issues/466 | The dependency `py-rust-stemmers` cannot be downloaded in a pure Python environment.

## 5. installation · 失败模式：installation: [Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: [Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2
- User impact: Developers may fail before the first successful local run: [Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2. Context: Observed when using python, windows, linux
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_04529bc774f1c961d4adeb7190edecd7 | https://github.com/qdrant/fastembed/issues/618 | [Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2

## 6. installation · 失败模式：installation: [Bug]: Unable to load 'Qdrant/bm25' on macOS python3.14

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: [Bug]: Unable to load 'Qdrant/bm25' on macOS python3.14
- User impact: Developers may fail before the first successful local run: [Bug]: Unable to load 'Qdrant/bm25' on macOS python3.14
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Unable to load 'Qdrant/bm25' on macOS python3.14. Context: Observed when using python, macos, cuda
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_79a43347d96beb6d05eb6bfec2503fb5 | https://github.com/qdrant/fastembed/issues/630 | [Bug]: Unable to load 'Qdrant/bm25' on macOS python3.14

## 7. installation · 失败模式：installation: v0.5.1

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v0.5.1
- User impact: Upgrade or migration may change expected behavior: v0.5.1
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v0.5.1. Context: Observed when using python
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_8b37c58c613005c0182d0325aaf032f7 | https://github.com/qdrant/fastembed/releases/tag/v0.5.1 | v0.5.1

## 8. installation · 来源证据：The dependency `py-rust-stemmers` cannot be downloaded in a pure Python environment.

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：The dependency `py-rust-stemmers` cannot be downloaded in a pure Python environment.
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_0f507b37e33e456ea259e82966cecdc5 | https://github.com/qdrant/fastembed/issues/466 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 9. configuration · 来源证据：[Bug]: No timeout on model download — requests.get() can hang indefinitely

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: No timeout on model download — requests.get() can hang indefinitely
- User impact: 可能阻塞安装或首次运行。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_6d570ba91cfd414f970a3a8da522be04 | https://github.com/qdrant/fastembed/issues/627 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 10. capability · 能力判断依赖假设

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: 假设不成立时，用户拿不到承诺的能力。
- Suggested check: 将假设转成下游验证清单。
- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。
- Evidence: capability.assumptions | github_repo:666260877 | https://github.com/qdrant/fastembed | README/documentation is current enough for a first validation pass.

## 11. runtime · 失败模式：runtime: [Bug]: Loading models with additional files fails with onnxruntime 1.24.1

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: [Bug]: Loading models with additional files fails with onnxruntime 1.24.1
- User impact: Developers may hit a documented source-backed failure mode: [Bug]: Loading models with additional files fails with onnxruntime 1.24.1
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Loading models with additional files fails with onnxruntime 1.24.1. Context: Observed when using python, linux
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_17b849ae47ffaf5d18cabbd577f373ca | https://github.com/qdrant/fastembed/issues/603 | [Bug]: Loading models with additional files fails with onnxruntime 1.24.1

## 12. runtime · 失败模式：runtime: v0.4.2

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: v0.4.2
- User impact: Upgrade or migration may change expected behavior: v0.4.2
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v0.4.2. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_607c8ff157108b2b5fb78f55129b60f6 | https://github.com/qdrant/fastembed/releases/tag/v0.4.2 | v0.4.2

## 13. runtime · 失败模式：runtime: v0.7.1

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: v0.7.1
- User impact: Upgrade or migration may change expected behavior: v0.7.1
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v0.7.1. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_07583dafa20e640a1720d7a77188475e | https://github.com/qdrant/fastembed/releases/tag/v0.7.1 | v0.7.1

## 14. runtime · 失败模式：runtime: v0.8.0

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: v0.8.0
- User impact: Upgrade or migration may change expected behavior: v0.8.0
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v0.8.0. Context: Observed when using python, cuda
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_054bae0c9c1667cf5568de7ecb7087c9 | https://github.com/qdrant/fastembed/releases/tag/v0.8.0 | v0.8.0

## 15. maintenance · 来源证据：[Bug]: license error in pypi metadata

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Bug]: license error in pypi metadata
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_017eda744ea84e679aeb5d77d41f7541 | https://github.com/qdrant/fastembed/issues/620 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 16. maintenance · 维护活跃度未知

- Severity: medium
- Evidence strength: source_linked
- Finding: 未记录 last_activity_observed。
- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。
- Evidence: evidence.maintainer_signals | github_repo:666260877 | https://github.com/qdrant/fastembed | last_activity_observed missing

## 17. security_permissions · 下游验证发现风险项

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: 下游已经要求复核，不能在页面中弱化。
- Suggested check: 进入安全/权限治理复核队列。
- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。
- Evidence: downstream_validation.risk_items | github_repo:666260877 | https://github.com/qdrant/fastembed | no_demo; severity=medium

## 18. security_permissions · 存在评分风险

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: 风险会影响是否适合普通用户安装。
- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。
- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。
- Evidence: risks.scoring_risks | github_repo:666260877 | https://github.com/qdrant/fastembed | no_demo; severity=medium

## 19. security_permissions · 来源证据：[Bug]: Loading models with additional files fails with onnxruntime 1.24.1

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Loading models with additional files fails with onnxruntime 1.24.1
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_cfcd79475b1344a0bba508ac4346edf4 | https://github.com/qdrant/fastembed/issues/603 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 20. security_permissions · 来源证据：[Bug]: Tar path traversal (Zip Slip) in decompress_to_cache — arbitrary file write outside cache directory

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Tar path traversal (Zip Slip) in decompress_to_cache — arbitrary file write outside cache directory
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_7603e6da390349c9aff6eed6cc5072a9 | https://github.com/qdrant/fastembed/issues/626 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 21. capability · 失败模式：capability: [Bug]: license error in pypi metadata

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: [Bug]: license error in pypi metadata
- User impact: Developers may hit a documented source-backed failure mode: [Bug]: license error in pypi metadata
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: license error in pypi metadata. Context: Observed when using python
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_9e209e0c78e000b92930bccb67db1440 | https://github.com/qdrant/fastembed/issues/620 | [Bug]: license error in pypi metadata

## 22. runtime · 失败模式：performance: [Bug]: No timeout on model download — requests.get() can hang indefinitely

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: [Bug]: No timeout on model download — requests.get() can hang indefinitely
- User impact: Developers may hit a documented source-backed failure mode: [Bug]: No timeout on model download — requests.get() can hang indefinitely
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: No timeout on model download — requests.get() can hang indefinitely. Context: Observed when using python, docker
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_69d0e997d6514a5d87d46c30a69795b3 | https://github.com/qdrant/fastembed/issues/627 | [Bug]: No timeout on model download — requests.get() can hang indefinitely

## 23. runtime · 失败模式：performance: v0.7.4

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: v0.7.4
- User impact: Upgrade or migration may change expected behavior: v0.7.4
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v0.7.4. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_df69e175afaf53788c9f212e22680b87 | https://github.com/qdrant/fastembed/releases/tag/v0.7.4 | v0.7.4

## 24. maintenance · issue/PR 响应质量未知

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: 用户无法判断遇到问题后是否有人维护。
- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。
- Guardrail action: issue/PR 响应未知时，必须提示维护风险。
- Evidence: evidence.maintainer_signals | github_repo:666260877 | https://github.com/qdrant/fastembed | issue_or_pr_quality=unknown

## 25. maintenance · 发布节奏不明确

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。
- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。
- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。
- Evidence: evidence.maintainer_signals | github_repo:666260877 | https://github.com/qdrant/fastembed | release_recency=unknown

## 26. maintenance · 失败模式：maintenance: v0.6.0

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.6.0
- User impact: Upgrade or migration may change expected behavior: v0.6.0
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v0.6.0. Context: Observed when using python
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_abc84a0766f60148974f2e932e8dc4f4 | https://github.com/qdrant/fastembed/releases/tag/v0.6.0 | v0.6.0

## 27. maintenance · 失败模式：maintenance: v0.6.1

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.6.1
- User impact: Upgrade or migration may change expected behavior: v0.6.1
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v0.6.1. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_e909fbcb26efacd532e8194ede2ff4f0 | https://github.com/qdrant/fastembed/releases/tag/v0.6.1 | v0.6.1

## 28. maintenance · 失败模式：maintenance: v0.7.0

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.7.0
- User impact: Upgrade or migration may change expected behavior: v0.7.0
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v0.7.0. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_0ccd78cc792f8d6a79212fc6cfa512e4 | https://github.com/qdrant/fastembed/releases/tag/v0.7.0 | v0.7.0

## 29. maintenance · 失败模式：maintenance: v0.7.2

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.7.2
- User impact: Upgrade or migration may change expected behavior: v0.7.2
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v0.7.2. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_28a8ed6e38ab5a351c6a64532998a7df | https://github.com/qdrant/fastembed/releases/tag/v0.7.2 | v0.7.2