FinMarketPy / 报错与版本边界
报错排查：五段定位顺序与三类「看起来是故障、其实不是」的提示
官方对报错几乎没有系统整理：README 里只单独讲了 Numba 一类，findatapy README 讲了 Redis 那条，其余要靠源码常量与发布说明推断。这一页把这些已知信息按定位顺序排好，并特别标出三条最容易被误判的东西——其中 Windows 回测默认单线程、缺 Redis 的报错无害、INSTALL.md 的年代错位，都是能实打实省下排查时间的信息。
pyproject.toml 的 numpy<2 约束、marketconstants.py 的线程表与 findatapy 的 Redis 说明）；示意非官方流程图，具体报错以你的实际输出为准。报错怎么查：先按段定位，再动手改
绝大多数报错都能落到五段之一。按顺序走，比直接改代码快得多——而且前三段基本不用读源码。
| 顺序 | 先确认什么 | 一次性命令 / 动作 | 落在这一段的典型现象 | 出口 |
|---|---|---|---|---|
| 1 依赖 | Python 版本、numpy 版本、三个库是否都在同一环境 | python -V；python -c "import numpy; print(numpy.__version__)"；打印三库路径 | ImportError、依赖解析失败、numpy 被降级、Numba 编译报错 | 见第二节 |
| 2 凭证与缓存 | key 是否生效、缓存组件缺不缺 | 用最小请求验证凭证；看是否有 Redis 相关提示 | 返回空表、Couldn't push MarketDataRequest | 见第三节 |
| 3 数据 | ticker 写法、字段名、时区与缺失 | 打印返回表的列名、索引时区与空值比例 | 列名不符、日期缺口、时间戳错位 | 见第四节 |
| 4 平台差异 | 操作系统、线程数、安装路径长度 | 看 marketconstants.py 的线程表默认值 | 并行很慢/不生效；路径相关失败 | 见第五节 |
| 5 输出 | 图表引擎、字体、Excel 文件写入 | 单独跑一次最小出图调用 | 无图片、字体方块、文件被占用 | 见第五节 |
依赖类报错怎么修
官方在这个方向上给了两条明确信息（numpy<2 与 FinancePy 的安装方式），其余可由依赖声明推出。
| 报错/现象 | 最可能原因 | 核对方法 | 处置方向 |
|---|---|---|---|
Failed in nopython mode pipeline 一类 Numba 报错 | Numba 编译缓存与当前环境不匹配（常见于 FinancePy） | 确认报错堆栈里指向 FinancePy/Numba | 官方解法：删除 FinancePy 安装目录下的 __pycache__ 文件夹（README 给了典型路径示例） |
| numpy 版本冲突 / 被强制降级 | 依赖声明是 numpy<2 | pip check；看环境里 numpy 实际版本 | 给 finmarketpy 单独虚拟环境，别与需要 numpy 2 的库共用 |
| 安装 FinancePy 时把一堆库搞坏 | FinancePy 对 llvmlite 等有严格版本约束 | 看安装日志里被连带升级/降级的库 | 官方方式：pip install financepy==0.370 --no-deps，并先手动装 numba/numpy/scipy/llvmlite/ipython/pandas/prettytable |
| ImportError：找不到 chartpy 或 findatapy | 两个前置库没装进同一环境 | 分别 import 一次看路径 | 按 安装页顺序重装 |
| pandas 相关 deprecation / 属性错误 | pandas 无上限约束，大版本升级后旧写法失效 | 看报错指向的方法名 | 回退到与发布版接近的 pandas；或等上游修复（0.11.19 发布说明即为调整 numpy/pandas 版本） |
| 装完 import 很慢或首次调用卡住 | numba 首次编译（JIT）属正常 | 第二次调用是否变快 | 属预期行为，不是故障 |
| 依赖解析把 scipy / statsmodels 一起动了 | findatapy 依赖面较宽（含 pandas-datareader、yfinance、statsmodels 等） | 比对安装前后的包清单 | 用独立环境隔离；或用 --no-deps 只升三个库 |
凭证与缓存类提示：哪些不是故障
这一段的误判率最高。下面把官方明确写过的行为和推断出来的行为分开列。
| 提示 / 现象 | 是不是故障 | 依据 | 该做什么 |
|---|---|---|---|
Couldn't push MarketDataRequest | 不是。只是缓存层没写成功（通常因为没装/没启动 Redis） | findatapy README 明确说明：其它功能不受影响，只是每次都去外部取数 | 数据能正常返回就忽略；想加速再装 Redis |
| 返回空 DataFrame（无报错） | 是。多半是凭证或 ticker | — | 先用已知可用的源与标准 ticker 做最小验证，再排查映射 |
| 提示需要 keyring / 首次运行要求输入 key | 不是故障，是设计 | INSTALL.md 说明：未建 cred 文件时会用 keyring 里的密码，并在首次运行提示输入 | 按提示录入，或用 cred 文件/按次传参 |
连到 127.0.0.1:27017 失败 | 看情况。finmarketpy 默认 db_server='127.0.0.1'、db_port='27017'、write_engine='arctic'、密码占位 'TOFILL' | util/marketconstants.py 默认值 | 不用数据库就把相关开关关掉/改正常量；要用就把地址密码改成自己的 |
| 读取本地经济事件文件失败 | 是。常量里 hdf5_file_econ_file 占位值是 "x" | 同上 | 用事件研究前先把该常量改成真实路径 |
| 升级包后凭证突然失效 | 是。直接改常量文件的路线会被覆盖 | findatapy README 推荐用 cred 文件或 keyring | 迁移到 datacred.py/marketcred.py 或 keyring |
INSTALL.md 当版本说明书。它 17 KB 的正文仍在讲 Anaconda py37class、Visual Studio 2017、pip install arctic 与 cufflinks（chartpy 后来已改用 Plotly Express）。照着它配环境会出现「文档里的包现在装不上/用不到」的情况。版本以 pyproject.toml 与 PyPI 元数据为准。| 现象 | 先查 | 再看 | 处置方向 |
|---|---|---|---|
| 某几个 ticker 一直没有数据 | ticker 与 vendor_ticker 是否一一对应 | 该序列在目标区间是否停更 | 对齐官方示例的 ticker 写法；缺失品种剔除 |
列名不是 close 而是别的 | fields 与 vendor_fields 的映射 | findatapy 的字段别名表 | 按别名表对齐；不要靠试错硬猜 |
| 回测里出现异常大或为空的仓位 | 信号表与行情表索引是否一致 | 信号列名与资产列名是否匹配 | 对齐索引与列名；再用 TechParams.fillna 明确缺失值策略 |
| 日期缺口导致净值曲线「平掉」 | 是否有非交易日的行 | 时区与日历是否统一 | 用日历工具对齐后再回测 |
| 数据「看起来是新的」但实际是旧的 | 缓存是否命中旧请求 | 数据源本身的更新时间 | 清缓存或换参数验证；记录取数时间 |
| 宏观序列的历史值和你记忆里的不一样 | 是否用了修订后数据 | 数据源的修订说明 | 记录数据版本；事件研究尤其要注意（见事件研究页） |
平台差异与输出类问题
这一段有两个实打实的官方事实：线程数的平台默认值，和 Numba 的缓存处置。
| 现象 | 原因 | 依据 | 处置方向 |
|---|---|---|---|
| 参数扫描 / 回测在 Windows 上明显慢 | backtest_thread_no = {'linux': 8, 'windows': 1, 'mac': 8}——Windows 默认只有 1 个线程 | util/marketconstants.py | 在 Windows 上要么接受串行、要么在 WSL/容器里跑；backtest_thread_technique 默认 multiprocessing，multiprocessing_library 默认 multiprocess，也可切换 |
| 并行开关开了但没变快 | run_in_parallel 的生效条件与数据量、平台有关 | 官方发布说明提到并行特性「在 Linux 上表现更好」 | 先用小数据量验证并行是否真的生效，再放大规模 |
| 出图没有生成文件 | chartpy 引擎未配好，或路径不可写 | style.file_output 的路径语义 | 用绝对路径试一次；确认 chartpy 已安装（见三库分工） |
| 图里中文变方块 | matplotlib 字体未配置 | INSTALL.md 提到 chartpy 默认字体为 Open Sans，需安装并删除 matplotlib 字体缓存（如 fontList.py3k.cache） | 安装字体 → 删缓存 → 重跑 |
| Excel 报告写入失败 | 文件被 Excel 占用；或依赖 openpyxl/xlsxwriter 缺失 | run_excel_trade_report(trading_model, excel_file='model.xlsx') 默认写 model.xlsx | 关闭已打开的 Excel；换文件名（也避免覆盖上一轮结果） |
| CSV 输出为空或位置找不到 | write_csv / write_csv_pnl 与路径设置 | BacktestRequest 输出开关 | 显式指定输出目录；确认工作目录 |
| 交互式图在 notebook 里不显示 | 引擎与 plotly 的嵌入模式设置 | 源码里有 PLOTLY_PLOT_MODE = "offline_html_exc_embed_js" 一类默认值 | 需要嵌 JS 时调整 plotly 模式；以你安装版本的源码为准 |
| Windows 下长路径相关失败 | 路径过深（官方在同类项目里提示过避免深目录） | 官方安装建议 | 把项目放在较短的路径下 |
报错与版本边界常见问题
处置方向以官方 README、pyproject.toml 与源码常量为依据；本站未实机验证，具体报错以你的实际输出为准。
哪一条报错最常见但其实无害？
Couldn't push MarketDataRequest。它是缓存层在提示写 Redis 失败，官方 README 说明得很清楚：没有 Redis 时这个缓存会失败，但所有其它功能都正常，只是每次都去外部数据源取数。所以看到它先别动，确认取回来的数据对不对才是正事。
为什么 Windows 上回测特别慢？
因为源码里的平台默认线程数是硬编码的：backtest_thread_no = {'linux': 8, 'windows': 1, 'mac': 8}。Windows 默认单线程，所以参数扫描、批量回测会比 Linux 慢很多。这是放在 util/marketconstants.py 里的常量，可以按机器情况调整（注意官方注释提示：线程开太多有些数据源会抱怨）。
numpy 2.x 到底能不能用？
依赖声明写的是 numpy<2，也就是说按官方声明不支持 2.x。硬装 2.x 可能某些功能能用，但属于超出官方声明的用法，出问题不要指望上游修。建议给finmarketpy单独一个环境，把 numpy 留在 1.x。以 pyproject.toml 与 PyPI 元数据为准。
装完提示找不到某个模块，但 pip list 里有，怎么回事？
九成是「两个环境串了」：pip 装到的环境和运行代码的解释器不是同一个（系统 Python vs 虚拟环境），或者是 PyPI 线与 git+ 线混装导致有两份包。最快的确认方式是分别打印三个库的 __file__，看路径是否都在你期望的环境目录下（安装页有这条命令）。
官方文档说要装一堆东西，我到底要不要都装？
不要照单全收。真正必需的只有：Python 环境、chartpy、findatapy、finmarketpy（以及可选的 FinancePy）。INSTALL.md 里列出的 Visual Studio 编译工具、arctic、blpapi、Redis、MongoDB、字体等，都是特定功能才需要的——比如 blpapi 只在你用 Bloomberg 时才装。那个文档的年代也偏旧（Python 3.5/3.6/3.7 时代），以 pyproject.toml 为准。
修不动了，有没有替代路径？
有两条：一是用官方 Binder notebook 在浏览器里跑示例（不装环境）；二是走免部署的 免部署技能路线先拿数据与结论。两条都不是finmarketpy的本地安装方式，能力覆盖也不同——具体对照见顶部导航的「对比」页。本站不承诺技能路线能替代 finmarketpy 的 curve/ 与事件研究能力。