Flower 退出码参考指南SuperLink、SuperNode、SuperExec 等组件错误码分类与处理方案【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower本文基于 Flower 官方文档中的退出码参考页ref-exit-codes-dir.rst及其索引下的全部子页面系统讲解 Flower 各组件SuperLink、SuperNode、SuperExec、ServerApp、ClientApp、CLI 与 Simulation的退出码分类体系、每个退出码的语义与推荐处理方式并结合源码 ExitCode 定义 说明其实现机制。读完后你可以快速读懂 Flower 进程退出时打印的错误码并按官方指引完成定位与修复。退出码分类体系Categories官方参考页将 Flower 的退出码按数值区间划分为若干类别不同区间的退出码对应不同组件的错误。文档原文给出的核心分类如下区间类别含义0-99Success exit codes进程成功完成的退出码100-199SuperLink-specificflower-superlinkSuperLink专属错误300-399SuperNode-specificflower-supernodeSuperNode专属错误400-499SuperExec-specificflower-superexecSuperExec专属错误600-699Common多个组件共享的通用退出码从源码结构看ExitCode 类中还额外划分了若干文档分类表未单独列出的区间完整区间划分如下区间类别说明200-249ServerApp-specificServerApp 运行时错误250-299ClientApp-specificClientApp 运行时错误500-599FlowerCLI-specificflwr命令行工具Flower CLI错误700-799Simulation仿真flwr-simulation错误800-899Task process任务进程错误值得注意的是源码中部分历史退出码已被显式删除并保留注释例如SUPERLINK_THREAD_CRASH 100、SUPERNODE_REST_ADDRESS_INVALID 300、COMMON_MISSING_EXTRA_REST 601均标注--- DELETED ---这意味着当前版本不会再产生这些码如果你在旧版环境中看到它们说明组件版本不匹配。退出码的实现机制ExitCode 与 EXIT_CODE_HELP所有退出码集中定义在 framework/py/flwr/supercore/exit/exit_code.py 中的ExitCode类里该类通过__new__禁止实例化仅作为常量命名空间使用class ExitCode: Exit codes for Flower components. # Success exit codes (0-99) SUCCESS 0 # Successful exit without any errors or signals GRACEFUL_EXIT_SIGINT 1 # Graceful exit triggered by SIGINT GRACEFUL_EXIT_SIGQUIT 2 # Graceful exit triggered by SIGQUIT GRACEFUL_EXIT_SIGTERM 3 # Graceful exit triggered by SIGTERM ...同一文件中还维护了一张EXIT_CODE_HELP字典见 exit_code.py#L86-L212为每个退出码提供一段简短帮助文本供进程退出时随退出码一并输出方便运维人员不查文档即可初步判断问题方向。例如SUPERLINK_LICENSE_MISSING对应的帮助文本直接提示“Please specify the license key by setting the environment variableFLWR_LICENSE_KEY.”优雅退出信号触发的退出的映射关系定义在 signal_handler.py 与 exit_handler.py 中SIGINT、SIGQUIT、SIGTERM分别映射到退出码 1、2、3。而具体错误码则由对应组件在检测到故障时主动触发退出例如 SuperLink 在许可证校验失败时直接调用flwr_exit(ExitCode.SUPERLINK_LICENSE_INVALID)见 control_grpc.py#L64。成功与信号退出码0-99退出码名称说明0SUCCESS进程正常完成1GRACEFUL_EXIT_SIGINT由SIGINT如 CtrlC触发的优雅退出2GRACEFUL_EXIT_SIGQUIT由SIGQUIT触发的优雅退出3GRACEFUL_EXIT_SIGTERM由SIGTERM如kill、容器停止触发的优雅退出这几个码表示组件按预期或按信号正常退出属于“成功退出码0-99”区间无需修复。在 K8s 等编排环境中Pod 终止时收到SIGTERM后以退出码 3 结束是正常现象不应被误判为故障。SuperLink 退出码100-199SuperLink 是整个 Flower 网络的中心控制组件其启动阶段的错误集中体现在 101-105。相关文档页面依次为 101.rst、102.rst、103.rst、104.rst、105.rst。退出码名称触发条件101SUPERLINK_LICENSE_INVALID许可证无效启动时提前退出102SUPERLINK_LICENSE_MISSING未提供许可证103SUPERLINK_LICENSE_URL_INVALID许可证 URL 无效104SUPERLINK_INVALID_ARGS启动参数无效或互相冲突105SUPERLINK_DATABASE_SCHEMA_MISMATCH数据库 schema 与基线 schema 不匹配101 SUPERLINK_LICENSE_INVALID。许可证无效会导致 SuperLink 在启动时提前退出。文档列出的可能原因有三环境变量FLWR_LICENSE_KEY被设置为无效的许可证密钥SuperLink 无法访问许可证服务器的公钥端点public key endpoint拉取到的公钥格式错误PEM 编码或密钥类型不对或其签名未能通过签名密钥校验。处理方式确认FLWR_LICENSE_KEY有效确认公钥端点配置正确且 SuperLink 可以访问若问题依旧联系官方支持。102 SUPERLINK_LICENSE_MISSING。启动 SuperLink 时未设置许可证直接在启动阶段设置FLWR_LICENSE_KEY环境变量为有效密钥即可。103 SUPERLINK_LICENSE_URL_INVALID。许可证 URL 无效。处理方式启动时通过FLWR_LICENSE_URL环境变量提供有效的许可证 URL并确认该 URL 指向能够提供许可证信息的合法许可证服务器。104 SUPERLINK_INVALID_ARGS。SuperLink 以无效参数启动。文档指出部分传入的参数彼此不兼容应查看 SuperLink 日志其中包含针对该冲突的进一步提示。结合EXIT_CODE_HELP中的帮助文本也可以先运行--help检查正确用法。105 SUPERLINK_DATABASE_SCHEMA_MISMATCH。SuperLink 启动时检测到数据库 schema 与预期的基线 schema 不一致。文档说明这通常发生在使用需要迁移的、且已被手工修改过的 pre-Alembic 数据库时。处理方式先备份数据库然后要么将其手工迁移到基线 schema要么使用一个全新数据库重新起步。ServerApp 退出码200-249ServerApp 承载联邦训练/评估的服务器端逻辑策略、聚合等其运行期错误对应 200.rst、201.rst、202.rst、203.rst。退出码名称触发条件200SERVERAPP_STRATEGY_PRECONDITION_UNMET策略收到的回复无法聚合201SERVERAPP_EXCEPTIONServerApp 代码抛出未处理异常202SERVERAPP_STRATEGY_AGGREGATION_ERROR聚合过程中发生错误203SERVERAPP_RUN_START_REJECTEDSuperLink 拒绝启动该 run200 SERVERAPP_STRATEGY_PRECONDITION_UNMET是最值得细看的一个。文档说明策略strategy收到的回复无法被聚合原因可能是各回复中受支持的记录数量不对、各记录内部使用的键key与其他回复不一致或策略执行加权平均所需的键缺失。解决原则所有 ClientApp 返回的回复中必须包含一个ArrayRecord当消息类型为MessageType.EVALUATE即评估轮次时无需ArrayRecord和一个MetricRecord所有回复中的记录必须使用完全相同的键若策略依赖某个键做加权平均例如FedAvg返回的MetricRecord必须包含该键。文档给出了两类RecordDict载荷示例假设ServerApp配置了使用FedAvg且以num-examples作为加权键可以聚合的两组载荷——键完全一致、各含一条记录、且加权键存在payload1 RecordDict( { model-parameters: ArrayRecord(...), # 评估轮次中没有 ArrayRecord metrics: MetricRecord({loss: 0.123, num-examples: 1234}), } ) payload2 RecordDict( { model-parameters: ArrayRecord(...), # 评估轮次中没有 ArrayRecord metrics: MetricRecord({loss: 0.01, num-examples: 1234}), } )不可聚合的情况一键不匹配一个含loss另一个含loss与accuracypayload1 RecordDict( { model-parameters: ArrayRecord(...), metrics: MetricRecord({loss: 0.123, num-examples: 1234}), } ) payload2 RecordDict( { model-parameters: ArrayRecord(...), metrics: MetricRecord({loss: 0.01, accuracy: 0.99, num-examples: 1234}), } )不可聚合的情况二缺少ArrayRecordpayload1 RecordDict( { model-parameters: ArrayRecord(...), metrics: MetricRecord({loss: 0.123, num-examples: 1234}), } ) payload2 RecordDict({metrics: MetricRecord({loss: 0.01, num-examples: 1234})})不可聚合的情况三缺少加权平均所需的键两个MetricRecord都没有num-examplespayload1 RecordDict( { model-parameters: ArrayRecord(...), metrics: MetricRecord({loss: 0.123, accuracy: 0.83}), } ) payload2 RecordDict( { model-parameters: ArrayRecord(...), metrics: MetricRecord({loss: 0.01, accuracy: 0.99}), } )201 SERVERAPP_EXCEPTION。ServerApp 代码执行期间抛出未处理异常。文档建议查看日志中记录的异常详情仔细检查自己的代码并修复根本原因。202 SERVERAPP_STRATEGY_AGGREGATION_ERROR。策略在聚合过程中遇到错误。处理方式查看日志获取具体聚合错误的详情。203 SERVERAPP_RUN_START_REJECTED。SuperLink 拒绝了启动 run 的请求。文档列出的三种场景及对应排查动作run 已被其他进程或用户停止——先检查 run 状态ServerApp 未能在允许时间内完成启动文档特别指出 ServerApp 中缓慢的导入可能导致超时——验证 SuperExec 能否在时限内启动 ServerApprun ID 或 FAB 无效或 SuperLink 数据库状态不正确——确认 SuperLink 数据库状态正常、未被损坏。ClientApp 退出码250-299当前版本仅定义了一个 ClientApp 退出码见 250.rst250 CLIENTAPP_COMMUNICATION_ERROR。运行期间ClientApp 的进程无法与 SuperNode Runtime API 通信。文档给出的排查路径查看 run 输出以及周边 SuperNode 与 SuperExec 进程的日志以定位底层 gRPC 错误这些进程默认向日志输出到 stdout/stderr容器化部署时应检查相应 SuperNode 和 SuperExec 的 Pod/容器日志一个典型原因是 ClientApp 进程启动耗时过长例如系统非常缓慢或过载导致超时若日志不足以定位问题联系 Flower 团队并提供相关的 run、SuperNode、SuperExec/ClientApp 日志。SuperNode 退出码300-399SuperNode 相关的三个退出码集中在节点认证与 TLS 配置上302.rst、303.rst、304.rst退出码名称触发条件302SUPERNODE_NODE_AUTH_KEY_INVALID节点认证私钥文件无效或不可读303SUPERNODE_STARTED_WITHOUT_TLS_BUT_NODE_AUTH_ENABLED启用了节点认证但未启用 TLS304SUPERNODE_INVALID_TRUSTED_ENTITIES受信任实体 YAML 文件无效302 SUPERNODE_NODE_AUTH_KEY_INVALID。节点认证要求一个有效的椭圆曲线私钥。当--auth-supernode-private-key指定的私钥文件无效或不可读时触发。处理方式确认私钥选项提供的文件路径正确确认文件存在且包含有效的椭圆曲线 SSH 密钥若文件损坏或格式不对重新生成椭圆曲线 SSH 密钥对并更新文件路径。文档给出仅用于快速原型验证非生产环境生产应遵循公司的密钥管理流程的示例ssh-keygen -t ecdsa -b 384 -N -f id_ecdsa_nistp384303 SUPERNODE_STARTED_WITHOUT_TLS_BUT_NODE_AUTH_ENABLED。提供了 SuperNode 认证私钥但未启用 TLS——SuperNode 认证要求与 SuperLink 之间建立安全的 TLS 连接。处理方式二选一启动 SuperNode 时提供 TLS 证书以启用 TLS$ flower-supernode \ --root-certificates path/to/your/ca.crt \ --superlinksuperlink-address如果处于原型验证阶段也可以移除私钥参数来禁用 CLI 管理的 SuperNode 认证机制SuperNode 将改用自动认证机制。文档同时建议阅读其引用的《how to enable TLS in SuperNode》与《how to authenticate SuperNodes》两篇指南位于framework/docs/source/目录以了解两种认证模式的完整细节。304 SUPERNODE_INVALID_TRUSTED_ENTITIES。通过--trusted-entities提供的受信任实体 YAML 文件无效SuperNode 必须使用合法的受信任实体列表重启。处理方式提供合法的受信任实体列表例如--trusted-entities ./pks.yaml该 YAML 文件包含受信任实体的公钥 ID 及其公钥并需满足公钥必须为OpenSSH 格式当前仅支持ssh-ed25519密钥类型公钥 ID 必须遵循fpk_UUID格式其中fpk是 Flower Public Key 的缩写YAML 文件结构如下fpk_UUID1: ssh-ed25519 base64-encoded-key1 [comment1]* fpk_UUID2: ssh-ed25519 base64-encoded-key2 [comment2]*注释部分可选或者移除--trusted-entities选项禁用实体校验使 SuperNode 在不进行实体校验的情况下运行。SuperExec 退出码400-499SuperExec 负责在 SuperNode 上拉起 ServerApp/ClientApp 等应用进程其配置类错误对应 400.rst、401.rst、402.rst退出码名称触发条件400SUPEREXEC_INVALID_PLUGIN_CONFIGSuperExec 插件 YAML 配置无效401SUPEREXEC_AUTH_SECRET_LOAD_FAILED认证密钥文件加载失败402SUPEREXEC_INVALID_EXECUTOR_CONFIG执行器executor配置无法选择/加载/应用400 SUPEREXEC_INVALID_PLUGIN_CONFIG。SuperExec 插件的 YAML 配置无效、无法解析或提供的路径不正确。处理步骤确认配置文件路径正确且文件存在确认文件是合法的 YAML 文档确认文件结构符合所用 SuperExec 插件预期的 schema根据伴随的错误信息定位非法部分并修正语法或结构问题。401 SUPEREXEC_AUTH_SECRET_LOAD_FAILED。SuperExec 无法从提供的密钥文件加载认证密钥。处理步骤确认--superexec-auth-secret-file路径存在且可读确认密钥文件非空查看伴随错误信息中具体的文件访问/校验失败原因。402 SUPEREXEC_INVALID_EXECUTOR_CONFIG。SuperExec 的执行器无法被选中或其配置无法加载、解析或应用。处理步骤确认所选--executor受当前 Flower 版本支持确认--executor-config路径存在且可读确认文件为合法 YAML且 YAML 文档是一个 mapping键值映射根据伴随错误信息定位具体失败点。Flower CLI 退出码500-599当前版本定义了 1 个 Flower CLI 退出码见 500.rst500 FLWRCLI_NODE_AUTH_PUBLIC_KEY_INVALID。flwr supernode register提供的公钥文件无效。节点认证要求一个合法的、SSH 格式的椭圆曲线公钥。处理步骤确认公钥选项提供的文件路径正确确认文件存在且包含符合 NIST 标准椭圆曲线例如 SECP384R1的 SSH 格式 ECDSA 公钥若文件损坏或格式不对重新生成椭圆曲线密钥对并更新路径。文档给出仅用于快速原型验证的示例ssh-keygen -t ecdsa -b 384 -N -f id_ecdsa_nistp384通用退出码600-699通用退出码Common被多个组件共享是日常部署中最常遇到的一组600.rst、602.rst、603.rst、604.rst、605.rst、606.rst、607.rst、608.rst退出码名称触发条件600COMMON_ADDRESS_INVALID地址无效或无法解析602COMMON_TLS_NOT_SUPPORTED使用了不支持 TLS 的组件603COMMON_TLS_ROOT_CERTIFICATES_INCOMPATIBLE--root-certificates与--insecure同时使用604COMMON_PATH_INVALID路径无效或不是预期文件605COMMON_TLS_SERVER_CERTIFICATES_INVALIDTLS 服务端证书配置不完整606RUNTIME_VERSION_INCOMPATIBLEFlower 运行时版本不兼容607COMMON_APP_IMPORT_ERRORFlower App 导入失败608COMMON_RUNTIME_DEPENDENCY_INSTALLATION_ERROR运行时依赖安装失败600 COMMON_ADDRESS_INVALID。提供的地址无效且无法解析必须是合法的 URL、IPv4 或 IPv6 地址。文档给出的合法格式示例URL如https://127.0.0.1:8080或https://example.com:8080IPv4如192.168.1.1:9091IPv6如[2001:0db8::1]:9092602 COMMON_TLS_NOT_SUPPORTED。文档明确说明flower-superexec、flwr-serverapp、flwr-simulation与flwr-clientapp目前不支持 TLS因为这些组件假定与各自对应的长驻进程flower-superlink、flower-supernode运行在同一网络内。处理方式使用--insecure标志在无 TLS 的情况下继续运行。603 COMMON_TLS_ROOT_CERTIFICATES_INCOMPATIBLE。--root-certificates与--insecure同时出现时触发二者互斥--insecure会禁用 TLS。处理方式二选一移除--insecure以配合--root-certificates使用 TLS或移除--root-certificates以无 TLS 运行。604 COMMON_PATH_INVALID。路径无效或不是预期文件。处理方式确认路径存在、指向预期的文件类型、且当前进程可读根据错误信息定位是哪个选项或文件路径导致失败。605 COMMON_TLS_SERVER_CERTIFICATES_INVALID。TLS 服务端证书配置不完整或无效。处理方式为要启动的服务提供全部必需的 TLS 服务端证书选项或移除不完整的 TLS 配置根据错误信息确认该服务具体需要哪些证书选项。606 RUNTIME_VERSION_INCOMPATIBLE。Flower 各运行时组件版本不兼容。处理方式查看错误信息其中可能直接给出要求的 Flower 版本——若指定了版本安装该版本$ pip install flwrversion否则升级 Flower$ pip install -U flwr607 COMMON_APP_IMPORT_ERROR。Flower 无法加载 Flower App因为其代码导入失败可能是缺少依赖、找不到 app 中的模块或导入的函数/类名不存在。处理方式分两类若缺失的是 app 自身的模块或.py文件确认该文件已包含在 app 中且导入名正确若缺失的是已有模块中的某个名字确认该函数、类或变量存在且被该模块导出若缺失的是第三方库依赖取决于依赖安装方式——若启用了自动运行时依赖安装把缺失的包加入 app 的pyproject.toml依赖后重跑若未启用则在 ServerApp/ClientApp 进程运行的 Python 环境中手动安装缺失包或者考虑启用自动运行时依赖安装。608 COMMON_RUNTIME_DEPENDENCY_INSTALLATION_ERROR。Flower App 依赖的运行时安装失败。处理方式查看日志中的uv sync错误。文档列出常见失败原因包索引不可达配置的索引上不存在该包或版本凭证或代理设置无效声明的依赖与当前 Python 环境不兼容。相应地应核验 apppyproject.toml中声明的依赖包名、版本约束、Python 兼容性若宿主机需要自定义包索引配置 uv 原生的UV_DEFAULT_INDEX并确认所需包在该索引上可用若环境不允许运行时安装依赖则预装 Flower App 依赖并禁用运行时依赖安装。Simulation 与任务进程退出码700-899从源码结构看ExitCode还保留了 Simulation700-799与 Task process800-899两个区间当前各定义 2 个/1 个退出码700 SIMULATION_EXCEPTION见 700.rst。运行仿真时发生未处理异常。处理方式确认启动仿真的 SuperExec 环境已安装并正确配置了所有必要依赖检查仿真日志以定位具体异常及其原因参考其引用的《how to run Simulations》指南位于framework/docs/source/目录了解最佳实践与常见陷阱。701 SIMULATION_MISSING_EXTRA见 701.rst。仿真所需的可选依赖extra缺失。要使用 Ray 后端运行仿真需将flwr[simulation]加入 app 的pyproject.toml依赖dependencies [ flwr[simulation], ]之后手动安装 app 依赖除非启用了自动运行时依赖安装然后重试。800 TASK_PROC_EXCEPTION见 800.rst。任务进程中发生未处理异常。处理方式查看任务进程日志其中包含异常的详细信息与堆栈跟踪。使用退出码进行诊断的建议流程综合上述各条目的“如何修复”指引可以归纳出一个统一的排查流程先定位区间根据退出码数值确定故障组件0-99 为正常/信号退出100 起依次为 SuperLink、ServerApp/ClientApp、SuperNode、SuperExec、CLI、通用、Simulation、任务进程再去查对应组件的日志读伴随帮助文本EXIT_CODE_HELP会随退出码输出简短提示见 exit_code.py#L86-L212通常已指明应设置哪个环境变量、检查哪个文件或启用哪个开关按官方指引逐项核对许可证类问题核对FLWR_LICENSE_KEY/FLWR_LICENSE_URL认证与 TLS 类问题核对私钥/公钥文件格式与--insecure/--root-certificates的互斥关系聚合类问题200核对 ClientApp 返回的RecordDict键一致性容器化环境查对日志源gRPC/通信类错误如 250需要同时查看 run 输出、SuperNode 与 SuperExec 的 Pod/容器日志而不是只看单一进程版本不匹配优先处理606 及被标记DELETED的旧退出码都指向版本不一致先按错误信息中的版本号对齐各组件的 Flower 版本再排查其他问题。文档组织方式每个退出码一个独立页面从参考页的目录组织可以看出其可维护性设计索引页 ref-exit-codes-dir.rst 通过toctree的:glob:选项自动纳入ref-exit-codes/目录下的全部页面新增退出码时无需手工维护索引每个退出码对应framework/docs/source/ref-exit-codes/目录下以数值命名的独立 RST 文件如 0.rst、101.rst统一采用“Description How to Resolve”两节结构目录内的 _template.rst 提供了标准模板标题形如[CODE] NAME正文固定包含Description与How to Resolve两个小节。贡献者新增退出码时只需在ExitCode类中定义常量、补充EXIT_CODE_HELP帮助文本并按模板创建对应的 RST 页面即可文档会自动通过 glob 索引生效。【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Flower 退出码参考指南：SuperLink、SuperNode、SuperExec 等组件错误码分类与处理方案
Flower 退出码参考指南SuperLink、SuperNode、SuperExec 等组件错误码分类与处理方案【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower本文基于 Flower 官方文档中的退出码参考页ref-exit-codes-dir.rst及其索引下的全部子页面系统讲解 Flower 各组件SuperLink、SuperNode、SuperExec、ServerApp、ClientApp、CLI 与 Simulation的退出码分类体系、每个退出码的语义与推荐处理方式并结合源码 ExitCode 定义 说明其实现机制。读完后你可以快速读懂 Flower 进程退出时打印的错误码并按官方指引完成定位与修复。退出码分类体系Categories官方参考页将 Flower 的退出码按数值区间划分为若干类别不同区间的退出码对应不同组件的错误。文档原文给出的核心分类如下区间类别含义0-99Success exit codes进程成功完成的退出码100-199SuperLink-specificflower-superlinkSuperLink专属错误300-399SuperNode-specificflower-supernodeSuperNode专属错误400-499SuperExec-specificflower-superexecSuperExec专属错误600-699Common多个组件共享的通用退出码从源码结构看ExitCode 类中还额外划分了若干文档分类表未单独列出的区间完整区间划分如下区间类别说明200-249ServerApp-specificServerApp 运行时错误250-299ClientApp-specificClientApp 运行时错误500-599FlowerCLI-specificflwr命令行工具Flower CLI错误700-799Simulation仿真flwr-simulation错误800-899Task process任务进程错误值得注意的是源码中部分历史退出码已被显式删除并保留注释例如SUPERLINK_THREAD_CRASH 100、SUPERNODE_REST_ADDRESS_INVALID 300、COMMON_MISSING_EXTRA_REST 601均标注--- DELETED ---这意味着当前版本不会再产生这些码如果你在旧版环境中看到它们说明组件版本不匹配。退出码的实现机制ExitCode 与 EXIT_CODE_HELP所有退出码集中定义在 framework/py/flwr/supercore/exit/exit_code.py 中的ExitCode类里该类通过__new__禁止实例化仅作为常量命名空间使用class ExitCode: Exit codes for Flower components. # Success exit codes (0-99) SUCCESS 0 # Successful exit without any errors or signals GRACEFUL_EXIT_SIGINT 1 # Graceful exit triggered by SIGINT GRACEFUL_EXIT_SIGQUIT 2 # Graceful exit triggered by SIGQUIT GRACEFUL_EXIT_SIGTERM 3 # Graceful exit triggered by SIGTERM ...同一文件中还维护了一张EXIT_CODE_HELP字典见 exit_code.py#L86-L212为每个退出码提供一段简短帮助文本供进程退出时随退出码一并输出方便运维人员不查文档即可初步判断问题方向。例如SUPERLINK_LICENSE_MISSING对应的帮助文本直接提示“Please specify the license key by setting the environment variableFLWR_LICENSE_KEY.”优雅退出信号触发的退出的映射关系定义在 signal_handler.py 与 exit_handler.py 中SIGINT、SIGQUIT、SIGTERM分别映射到退出码 1、2、3。而具体错误码则由对应组件在检测到故障时主动触发退出例如 SuperLink 在许可证校验失败时直接调用flwr_exit(ExitCode.SUPERLINK_LICENSE_INVALID)见 control_grpc.py#L64。成功与信号退出码0-99退出码名称说明0SUCCESS进程正常完成1GRACEFUL_EXIT_SIGINT由SIGINT如 CtrlC触发的优雅退出2GRACEFUL_EXIT_SIGQUIT由SIGQUIT触发的优雅退出3GRACEFUL_EXIT_SIGTERM由SIGTERM如kill、容器停止触发的优雅退出这几个码表示组件按预期或按信号正常退出属于“成功退出码0-99”区间无需修复。在 K8s 等编排环境中Pod 终止时收到SIGTERM后以退出码 3 结束是正常现象不应被误判为故障。SuperLink 退出码100-199SuperLink 是整个 Flower 网络的中心控制组件其启动阶段的错误集中体现在 101-105。相关文档页面依次为 101.rst、102.rst、103.rst、104.rst、105.rst。退出码名称触发条件101SUPERLINK_LICENSE_INVALID许可证无效启动时提前退出102SUPERLINK_LICENSE_MISSING未提供许可证103SUPERLINK_LICENSE_URL_INVALID许可证 URL 无效104SUPERLINK_INVALID_ARGS启动参数无效或互相冲突105SUPERLINK_DATABASE_SCHEMA_MISMATCH数据库 schema 与基线 schema 不匹配101 SUPERLINK_LICENSE_INVALID。许可证无效会导致 SuperLink 在启动时提前退出。文档列出的可能原因有三环境变量FLWR_LICENSE_KEY被设置为无效的许可证密钥SuperLink 无法访问许可证服务器的公钥端点public key endpoint拉取到的公钥格式错误PEM 编码或密钥类型不对或其签名未能通过签名密钥校验。处理方式确认FLWR_LICENSE_KEY有效确认公钥端点配置正确且 SuperLink 可以访问若问题依旧联系官方支持。102 SUPERLINK_LICENSE_MISSING。启动 SuperLink 时未设置许可证直接在启动阶段设置FLWR_LICENSE_KEY环境变量为有效密钥即可。103 SUPERLINK_LICENSE_URL_INVALID。许可证 URL 无效。处理方式启动时通过FLWR_LICENSE_URL环境变量提供有效的许可证 URL并确认该 URL 指向能够提供许可证信息的合法许可证服务器。104 SUPERLINK_INVALID_ARGS。SuperLink 以无效参数启动。文档指出部分传入的参数彼此不兼容应查看 SuperLink 日志其中包含针对该冲突的进一步提示。结合EXIT_CODE_HELP中的帮助文本也可以先运行--help检查正确用法。105 SUPERLINK_DATABASE_SCHEMA_MISMATCH。SuperLink 启动时检测到数据库 schema 与预期的基线 schema 不一致。文档说明这通常发生在使用需要迁移的、且已被手工修改过的 pre-Alembic 数据库时。处理方式先备份数据库然后要么将其手工迁移到基线 schema要么使用一个全新数据库重新起步。ServerApp 退出码200-249ServerApp 承载联邦训练/评估的服务器端逻辑策略、聚合等其运行期错误对应 200.rst、201.rst、202.rst、203.rst。退出码名称触发条件200SERVERAPP_STRATEGY_PRECONDITION_UNMET策略收到的回复无法聚合201SERVERAPP_EXCEPTIONServerApp 代码抛出未处理异常202SERVERAPP_STRATEGY_AGGREGATION_ERROR聚合过程中发生错误203SERVERAPP_RUN_START_REJECTEDSuperLink 拒绝启动该 run200 SERVERAPP_STRATEGY_PRECONDITION_UNMET是最值得细看的一个。文档说明策略strategy收到的回复无法被聚合原因可能是各回复中受支持的记录数量不对、各记录内部使用的键key与其他回复不一致或策略执行加权平均所需的键缺失。解决原则所有 ClientApp 返回的回复中必须包含一个ArrayRecord当消息类型为MessageType.EVALUATE即评估轮次时无需ArrayRecord和一个MetricRecord所有回复中的记录必须使用完全相同的键若策略依赖某个键做加权平均例如FedAvg返回的MetricRecord必须包含该键。文档给出了两类RecordDict载荷示例假设ServerApp配置了使用FedAvg且以num-examples作为加权键可以聚合的两组载荷——键完全一致、各含一条记录、且加权键存在payload1 RecordDict( { model-parameters: ArrayRecord(...), # 评估轮次中没有 ArrayRecord metrics: MetricRecord({loss: 0.123, num-examples: 1234}), } ) payload2 RecordDict( { model-parameters: ArrayRecord(...), # 评估轮次中没有 ArrayRecord metrics: MetricRecord({loss: 0.01, num-examples: 1234}), } )不可聚合的情况一键不匹配一个含loss另一个含loss与accuracypayload1 RecordDict( { model-parameters: ArrayRecord(...), metrics: MetricRecord({loss: 0.123, num-examples: 1234}), } ) payload2 RecordDict( { model-parameters: ArrayRecord(...), metrics: MetricRecord({loss: 0.01, accuracy: 0.99, num-examples: 1234}), } )不可聚合的情况二缺少ArrayRecordpayload1 RecordDict( { model-parameters: ArrayRecord(...), metrics: MetricRecord({loss: 0.123, num-examples: 1234}), } ) payload2 RecordDict({metrics: MetricRecord({loss: 0.01, num-examples: 1234})})不可聚合的情况三缺少加权平均所需的键两个MetricRecord都没有num-examplespayload1 RecordDict( { model-parameters: ArrayRecord(...), metrics: MetricRecord({loss: 0.123, accuracy: 0.83}), } ) payload2 RecordDict( { model-parameters: ArrayRecord(...), metrics: MetricRecord({loss: 0.01, accuracy: 0.99}), } )201 SERVERAPP_EXCEPTION。ServerApp 代码执行期间抛出未处理异常。文档建议查看日志中记录的异常详情仔细检查自己的代码并修复根本原因。202 SERVERAPP_STRATEGY_AGGREGATION_ERROR。策略在聚合过程中遇到错误。处理方式查看日志获取具体聚合错误的详情。203 SERVERAPP_RUN_START_REJECTED。SuperLink 拒绝了启动 run 的请求。文档列出的三种场景及对应排查动作run 已被其他进程或用户停止——先检查 run 状态ServerApp 未能在允许时间内完成启动文档特别指出 ServerApp 中缓慢的导入可能导致超时——验证 SuperExec 能否在时限内启动 ServerApprun ID 或 FAB 无效或 SuperLink 数据库状态不正确——确认 SuperLink 数据库状态正常、未被损坏。ClientApp 退出码250-299当前版本仅定义了一个 ClientApp 退出码见 250.rst250 CLIENTAPP_COMMUNICATION_ERROR。运行期间ClientApp 的进程无法与 SuperNode Runtime API 通信。文档给出的排查路径查看 run 输出以及周边 SuperNode 与 SuperExec 进程的日志以定位底层 gRPC 错误这些进程默认向日志输出到 stdout/stderr容器化部署时应检查相应 SuperNode 和 SuperExec 的 Pod/容器日志一个典型原因是 ClientApp 进程启动耗时过长例如系统非常缓慢或过载导致超时若日志不足以定位问题联系 Flower 团队并提供相关的 run、SuperNode、SuperExec/ClientApp 日志。SuperNode 退出码300-399SuperNode 相关的三个退出码集中在节点认证与 TLS 配置上302.rst、303.rst、304.rst退出码名称触发条件302SUPERNODE_NODE_AUTH_KEY_INVALID节点认证私钥文件无效或不可读303SUPERNODE_STARTED_WITHOUT_TLS_BUT_NODE_AUTH_ENABLED启用了节点认证但未启用 TLS304SUPERNODE_INVALID_TRUSTED_ENTITIES受信任实体 YAML 文件无效302 SUPERNODE_NODE_AUTH_KEY_INVALID。节点认证要求一个有效的椭圆曲线私钥。当--auth-supernode-private-key指定的私钥文件无效或不可读时触发。处理方式确认私钥选项提供的文件路径正确确认文件存在且包含有效的椭圆曲线 SSH 密钥若文件损坏或格式不对重新生成椭圆曲线 SSH 密钥对并更新文件路径。文档给出仅用于快速原型验证非生产环境生产应遵循公司的密钥管理流程的示例ssh-keygen -t ecdsa -b 384 -N -f id_ecdsa_nistp384303 SUPERNODE_STARTED_WITHOUT_TLS_BUT_NODE_AUTH_ENABLED。提供了 SuperNode 认证私钥但未启用 TLS——SuperNode 认证要求与 SuperLink 之间建立安全的 TLS 连接。处理方式二选一启动 SuperNode 时提供 TLS 证书以启用 TLS$ flower-supernode \ --root-certificates path/to/your/ca.crt \ --superlinksuperlink-address如果处于原型验证阶段也可以移除私钥参数来禁用 CLI 管理的 SuperNode 认证机制SuperNode 将改用自动认证机制。文档同时建议阅读其引用的《how to enable TLS in SuperNode》与《how to authenticate SuperNodes》两篇指南位于framework/docs/source/目录以了解两种认证模式的完整细节。304 SUPERNODE_INVALID_TRUSTED_ENTITIES。通过--trusted-entities提供的受信任实体 YAML 文件无效SuperNode 必须使用合法的受信任实体列表重启。处理方式提供合法的受信任实体列表例如--trusted-entities ./pks.yaml该 YAML 文件包含受信任实体的公钥 ID 及其公钥并需满足公钥必须为OpenSSH 格式当前仅支持ssh-ed25519密钥类型公钥 ID 必须遵循fpk_UUID格式其中fpk是 Flower Public Key 的缩写YAML 文件结构如下fpk_UUID1: ssh-ed25519 base64-encoded-key1 [comment1]* fpk_UUID2: ssh-ed25519 base64-encoded-key2 [comment2]*注释部分可选或者移除--trusted-entities选项禁用实体校验使 SuperNode 在不进行实体校验的情况下运行。SuperExec 退出码400-499SuperExec 负责在 SuperNode 上拉起 ServerApp/ClientApp 等应用进程其配置类错误对应 400.rst、401.rst、402.rst退出码名称触发条件400SUPEREXEC_INVALID_PLUGIN_CONFIGSuperExec 插件 YAML 配置无效401SUPEREXEC_AUTH_SECRET_LOAD_FAILED认证密钥文件加载失败402SUPEREXEC_INVALID_EXECUTOR_CONFIG执行器executor配置无法选择/加载/应用400 SUPEREXEC_INVALID_PLUGIN_CONFIG。SuperExec 插件的 YAML 配置无效、无法解析或提供的路径不正确。处理步骤确认配置文件路径正确且文件存在确认文件是合法的 YAML 文档确认文件结构符合所用 SuperExec 插件预期的 schema根据伴随的错误信息定位非法部分并修正语法或结构问题。401 SUPEREXEC_AUTH_SECRET_LOAD_FAILED。SuperExec 无法从提供的密钥文件加载认证密钥。处理步骤确认--superexec-auth-secret-file路径存在且可读确认密钥文件非空查看伴随错误信息中具体的文件访问/校验失败原因。402 SUPEREXEC_INVALID_EXECUTOR_CONFIG。SuperExec 的执行器无法被选中或其配置无法加载、解析或应用。处理步骤确认所选--executor受当前 Flower 版本支持确认--executor-config路径存在且可读确认文件为合法 YAML且 YAML 文档是一个 mapping键值映射根据伴随错误信息定位具体失败点。Flower CLI 退出码500-599当前版本定义了 1 个 Flower CLI 退出码见 500.rst500 FLWRCLI_NODE_AUTH_PUBLIC_KEY_INVALID。flwr supernode register提供的公钥文件无效。节点认证要求一个合法的、SSH 格式的椭圆曲线公钥。处理步骤确认公钥选项提供的文件路径正确确认文件存在且包含符合 NIST 标准椭圆曲线例如 SECP384R1的 SSH 格式 ECDSA 公钥若文件损坏或格式不对重新生成椭圆曲线密钥对并更新路径。文档给出仅用于快速原型验证的示例ssh-keygen -t ecdsa -b 384 -N -f id_ecdsa_nistp384通用退出码600-699通用退出码Common被多个组件共享是日常部署中最常遇到的一组600.rst、602.rst、603.rst、604.rst、605.rst、606.rst、607.rst、608.rst退出码名称触发条件600COMMON_ADDRESS_INVALID地址无效或无法解析602COMMON_TLS_NOT_SUPPORTED使用了不支持 TLS 的组件603COMMON_TLS_ROOT_CERTIFICATES_INCOMPATIBLE--root-certificates与--insecure同时使用604COMMON_PATH_INVALID路径无效或不是预期文件605COMMON_TLS_SERVER_CERTIFICATES_INVALIDTLS 服务端证书配置不完整606RUNTIME_VERSION_INCOMPATIBLEFlower 运行时版本不兼容607COMMON_APP_IMPORT_ERRORFlower App 导入失败608COMMON_RUNTIME_DEPENDENCY_INSTALLATION_ERROR运行时依赖安装失败600 COMMON_ADDRESS_INVALID。提供的地址无效且无法解析必须是合法的 URL、IPv4 或 IPv6 地址。文档给出的合法格式示例URL如https://127.0.0.1:8080或https://example.com:8080IPv4如192.168.1.1:9091IPv6如[2001:0db8::1]:9092602 COMMON_TLS_NOT_SUPPORTED。文档明确说明flower-superexec、flwr-serverapp、flwr-simulation与flwr-clientapp目前不支持 TLS因为这些组件假定与各自对应的长驻进程flower-superlink、flower-supernode运行在同一网络内。处理方式使用--insecure标志在无 TLS 的情况下继续运行。603 COMMON_TLS_ROOT_CERTIFICATES_INCOMPATIBLE。--root-certificates与--insecure同时出现时触发二者互斥--insecure会禁用 TLS。处理方式二选一移除--insecure以配合--root-certificates使用 TLS或移除--root-certificates以无 TLS 运行。604 COMMON_PATH_INVALID。路径无效或不是预期文件。处理方式确认路径存在、指向预期的文件类型、且当前进程可读根据错误信息定位是哪个选项或文件路径导致失败。605 COMMON_TLS_SERVER_CERTIFICATES_INVALID。TLS 服务端证书配置不完整或无效。处理方式为要启动的服务提供全部必需的 TLS 服务端证书选项或移除不完整的 TLS 配置根据错误信息确认该服务具体需要哪些证书选项。606 RUNTIME_VERSION_INCOMPATIBLE。Flower 各运行时组件版本不兼容。处理方式查看错误信息其中可能直接给出要求的 Flower 版本——若指定了版本安装该版本$ pip install flwrversion否则升级 Flower$ pip install -U flwr607 COMMON_APP_IMPORT_ERROR。Flower 无法加载 Flower App因为其代码导入失败可能是缺少依赖、找不到 app 中的模块或导入的函数/类名不存在。处理方式分两类若缺失的是 app 自身的模块或.py文件确认该文件已包含在 app 中且导入名正确若缺失的是已有模块中的某个名字确认该函数、类或变量存在且被该模块导出若缺失的是第三方库依赖取决于依赖安装方式——若启用了自动运行时依赖安装把缺失的包加入 app 的pyproject.toml依赖后重跑若未启用则在 ServerApp/ClientApp 进程运行的 Python 环境中手动安装缺失包或者考虑启用自动运行时依赖安装。608 COMMON_RUNTIME_DEPENDENCY_INSTALLATION_ERROR。Flower App 依赖的运行时安装失败。处理方式查看日志中的uv sync错误。文档列出常见失败原因包索引不可达配置的索引上不存在该包或版本凭证或代理设置无效声明的依赖与当前 Python 环境不兼容。相应地应核验 apppyproject.toml中声明的依赖包名、版本约束、Python 兼容性若宿主机需要自定义包索引配置 uv 原生的UV_DEFAULT_INDEX并确认所需包在该索引上可用若环境不允许运行时安装依赖则预装 Flower App 依赖并禁用运行时依赖安装。Simulation 与任务进程退出码700-899从源码结构看ExitCode还保留了 Simulation700-799与 Task process800-899两个区间当前各定义 2 个/1 个退出码700 SIMULATION_EXCEPTION见 700.rst。运行仿真时发生未处理异常。处理方式确认启动仿真的 SuperExec 环境已安装并正确配置了所有必要依赖检查仿真日志以定位具体异常及其原因参考其引用的《how to run Simulations》指南位于framework/docs/source/目录了解最佳实践与常见陷阱。701 SIMULATION_MISSING_EXTRA见 701.rst。仿真所需的可选依赖extra缺失。要使用 Ray 后端运行仿真需将flwr[simulation]加入 app 的pyproject.toml依赖dependencies [ flwr[simulation], ]之后手动安装 app 依赖除非启用了自动运行时依赖安装然后重试。800 TASK_PROC_EXCEPTION见 800.rst。任务进程中发生未处理异常。处理方式查看任务进程日志其中包含异常的详细信息与堆栈跟踪。使用退出码进行诊断的建议流程综合上述各条目的“如何修复”指引可以归纳出一个统一的排查流程先定位区间根据退出码数值确定故障组件0-99 为正常/信号退出100 起依次为 SuperLink、ServerApp/ClientApp、SuperNode、SuperExec、CLI、通用、Simulation、任务进程再去查对应组件的日志读伴随帮助文本EXIT_CODE_HELP会随退出码输出简短提示见 exit_code.py#L86-L212通常已指明应设置哪个环境变量、检查哪个文件或启用哪个开关按官方指引逐项核对许可证类问题核对FLWR_LICENSE_KEY/FLWR_LICENSE_URL认证与 TLS 类问题核对私钥/公钥文件格式与--insecure/--root-certificates的互斥关系聚合类问题200核对 ClientApp 返回的RecordDict键一致性容器化环境查对日志源gRPC/通信类错误如 250需要同时查看 run 输出、SuperNode 与 SuperExec 的 Pod/容器日志而不是只看单一进程版本不匹配优先处理606 及被标记DELETED的旧退出码都指向版本不一致先按错误信息中的版本号对齐各组件的 Flower 版本再排查其他问题。文档组织方式每个退出码一个独立页面从参考页的目录组织可以看出其可维护性设计索引页 ref-exit-codes-dir.rst 通过toctree的:glob:选项自动纳入ref-exit-codes/目录下的全部页面新增退出码时无需手工维护索引每个退出码对应framework/docs/source/ref-exit-codes/目录下以数值命名的独立 RST 文件如 0.rst、101.rst统一采用“Description How to Resolve”两节结构目录内的 _template.rst 提供了标准模板标题形如[CODE] NAME正文固定包含Description与How to Resolve两个小节。贡献者新增退出码时只需在ExitCode类中定义常量、补充EXIT_CODE_HELP帮助文本并按模板创建对应的 RST 页面即可文档会自动通过 glob 索引生效。【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考