fuels-ts 错误处理完全指南FuelError 类与 ErrorCode 错误码权威手册【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-tsFuel Network TypeScript SDKfuels-ts运行在浏览器与 Node.js 双端涉及的调用链路横跨 ABI 编解码、钱包签名、交易组装与 Fuel 节点 RPC 通信。为了让开发者能快速定位异常SDK 将所有内部错误统一收敛为FuelError类的实例并为每一种错误赋予一个唯一的ErrorCode。本指南以 错误处理官方文档 为主体结合 错误处理包源码 展开讲解你将掌握FuelError的类结构、ErrorCode的命名与取值规则、在代码中捕获与判断错误的标准姿势并获得一份覆盖全部预期错误码的「触发原因 → 解决方案」速查手册从而在实际开发中做到一眼识别、按码排查。一、统一错误模型一切异常都是FuelError文档开篇即给出 SDK 的核心设计约定所有从 SDK 抛出的错误都是FuelError类的实例并带有一个配套的ErrorCode。这意味着在业务代码中你不需要分别处理来自 ABI 编解码、钱包助记词、交易策略、RPC 请求等不同模块的各种错误类型只需学会判断「一个错误对象 一个错误码」即可。这一设计在 fuel-error.ts 中落地。FuelError继承自原生Error并在其上扩展了 5 个信息维度成员类型说明codeErrorCode唯一错误码用于程序化判断错误类别运行时取枚举的字符串值见下文metadataRecordstring, unknown可选的结构化附加信息默认{}rawErrorunknown原始底层错误如节点返回的错误默认nullnamestring恒为FuelError便于用err.name或日志系统识别VERSIONSversionsSDK 相关版本信息来自fuel-ts/versions随错误附带便于上报排查此外类上还有两个值得关注的静态/实例能力FuelError.CODES直接暴露ErrorCode枚举作为类型安全的错误码引用入口等价于import { ErrorCode } from fuel-ts/errorstoObject()把错误序列化为纯对象{ code, name, message, metadata, VERSIONS, rawError }方便通过 JSON 日志或 RPC 边界传递静态parse(e)把一个「看起来像 FuelError」的任意对象重新解析为合法的FuelError实例。它会先校验对象存在code属性再用Object.values(ErrorCode)校验该码是否在已知错误码集合中校验失败时会抛出一个code为PARSE_FAILED的FuelError相关行为由 fuel-error.test.ts 中的Parsing测试组覆盖。构造函数签名为new FuelError(code, message, metadata?, rawError?)其中message是必需的人类可读描述。下面这段来自 fuel-gauge 集成测试 的用例展示了最标准的构造方式await expectToThrowFuelError( () contract.functions.types_u8(input).call(), new FuelError(FuelError.CODES.ENCODE_ERROR, Invalid u8.) );二、ErrorCode枚举编码规则与命名差异全部错误码定义在 error-codes.ts 的ErrorCode枚举中并按照// abi、// provider、// wallet、// transaction、// mnemonic、// receipt、// chain、// errors等注释分区组织——从源码结构看注释分区即反映了错误码在 SDK 内部的模块归属例如 ABI 相关错误集中在枚举头部而UNKNOWN被单独放在文件末尾的// Unknown区。需要特别留意的一个细节是文档标题与运行值的差异文档中每个错误用小驼峰大写的枚举成员名如ABI_MAIN_METHOD_MISSING来指代而枚举成员的实际取值是kebab-case小写字符串例如ABI_MAIN_METHOD_MISSING abi-main-method-missing、INVALID_URL invalid-url。因此当你捕获错误并读取err.code时得到的是abi-main-method-missing这样的字符串值而不是大写的成员名。在使用switch、比较或把错误码写入日志/指标时请使用枚举引用ErrorCode.ABI_MAIN_METHOD_MISSING而非硬编码字符串这样既能获得类型提示也能避免拼写错误。值得强调的是错误码集合是动态演进的。文档正文覆盖的约 58 个错误码并非全量——源码中的ErrorCode枚举还包含NO_ABIS_FOUND、INVALID_ADDRESS、CONNECTION_REFUSED、MAX_FEE_TOO_LOW、TRANSACTION_SQUEEZED_OUT、INVALID_DECODE_VALUE、SCRIPT_REVERTED、NODE_LAUNCH_FAILED等更多内部错误码。如果你在运行中收到一个未出现在下文手册中的code可在 error-codes.ts 中查询其准确拼写与归属分区。三、捕获与处理FuelError的标准姿势结合FuelError的类结构处理 SDK 错误建议遵循以下流程import { FuelError, ErrorCode } from fuel-ts/errors; try { const result await contract.functions.increment(1).call(); // ... } catch (err) { // 关键结论SDK 抛出的错误统一是 FuelError可直接读取 code if (err instanceof FuelError err.code ErrorCode.FUNDS_TOO_LOW) { // 明确提示用户充值而不是笼统地报「调用失败」 console.error(余额不足${err.message}, err.metadata); } else if (err instanceof FuelError) { // 其它 SDK 错误展示 message并附带 code / metadata / rawError 便于上报 console.error(SDK 错误 [${err.code}]${err.message}, err.toObject()); } else { // 非 SDK 抛出的错误网络异常等原始错误 console.error(err); } }要点归纳用err instanceof FuelError或err.code ! undefined判断是否为 SDK 错误优先基于err.code分支处理因为code稳定、可枚举、可程序化匹配err.message面向开发者阅读包含可操作提示如缺失参数名、不合规的长度范围需要跨进程/跨语言传递或记录日志时使用err.toObject()得到可 JSON 化的扁平结构测试代码中可用官方测试工具expectToThrowFuelError(lambda, expectedError)精确断言「抛出的错误必须携带某个code、可选校验message/metadata/rawError」其实现位于 expect-to-throw-fuel-error.ts内部通过 safeExec 捕获并校验错误在 fuel-gauge 测试套件 中可看到大量实战用法。四、错误码速查手册触发原因 → 解决方案下文将文档中列出的全部错误码按业务域分组呈现每组内每条均保留文档给出的完整触发条件与解决建议并按源码中的模块归属标注了所属错误域方便交叉查阅 error-codes.ts。4.1 ABI 与数据编解码ABI_MAIN_METHOD_MISSINGabi 域当你的 ABI 中没有main方法时抛出。为 ABI 添加main方法即可解决这一约束在 script 和 predicate 中尤为普遍它们必须包含main方法。ABI_TYPES_AND_VALUES_MISMATCHabi 域传给函数的参数与函数要求的最小输入长度不匹配。请核对传入参数的个数与类型是否符合函数签名。FUNCTION_NOT_FOUNDabi 域在 ABI 中找不到给定名称、签名或 selector 对应的函数。请确认函数名、签名或 selector 拼写正确且确实存在于 ABI 中。INVALID_COMPONENTabi 域ABI 中缺少某个预期组件或该组件格式错误。请检查 Sway 中的 Array 与 Vector 类型是否书写正确。TYPE_NOT_FOUNDabi 域ABI 中找不到给定 type ID 对应的类型。请核对 type ID 是否正确且存在于 ABI。LOG_TYPE_NOT_FOUNDabi 域ABI 中找不到提供的日志类型 ID。请确认日志类型 ID 正确且已定义于 ABI。TYPE_NOT_SUPPORTEDabi 域检测到不期望的类型具体是哪个类型错误由错误消息给出。请对照 ABI 检查类型是否正确SDK 支持的全部类型可参考 类型文档。JSON_ABI_ERRORabi 域ABI 中某类型不符合正确的 JSON 格式。通常由程序内的错误类型引起可对照 类型文档 核对 SDK 支持的类型及其期望格式。INVALID_DATAabi 域传入的值按函数定义来看不合法。请检查函数签名确保传入值有效。CONVERTING_FAILEDerrors 域将大数big number转换为不兼容的格式时抛出。请确保你提供给大数的值与其要转换成的目标格式兼容。TIMEOUT_EXCEEDEDabi 域某个操作的超时时间已到。请确认你已连接网络且网络状态稳定。4.2 合约与 Sway 程序CONTRACT_SIZE_EXCEEDS_LIMITtransaction 域合约字节码超过最大合约大小限制时抛出。请确保合约大小低于 100 KB 上限可通过检查合约字节码长度来验证。INVALID_CONFIGURABLE_CONSTANTStransaction 域当程序类型没有可设置的 configurable constants或提供的 configurable constant 不属于该程序类型以其 ABI 定义为准时抛出。请确保提供的 configurable constants 正确且在 ABI 中已定义。ACCOUNT_REQUIREDwallet / account 域某项操作需要一个Account通常体现为Wallet时抛出。常见于部署合约时缺少用于签名的账户可参考 部署合约指南 解决。MISSING_PROVIDERprovider 域某项操作需要 provider 而缺失时抛出。常见原因是Account或Wallet未设置 provider可通过connect方法为它们挂载 provider。MISSING_CONNECTORwallet 域某项操作需要 connector连接器而缺失时抛出。请为Account或Wallet提供一个 connector。INVALID_INPUT_PARAMETERSerrors 域提供的输入参数不合法时抛出具体缺失项由错误消息说明——例如提供的程序类型不是contract、script、predicate三者之一。4.3 Provider、网络与 RPCINVALID_PROVIDERprovider 域无法连接到传给Fuel类方法的Provider或Network时抛出。请检查Provider或Network是否传入正确。MISSING_PROVIDERprovider 域同 4.2 中说明——请使用connect方法为Account或Wallet挂载 provider。NODE_INFO_CACHE_EMPTYprovider 域Fuel 节点信息缓存为空时抛出通常因为尚未连接到 Fuel 节点。请确保 provider 已成功连接一个 Fuel 节点。INVALID_REQUESTerrors 域对 Fuel 节点的请求失败错误消息由 Fuel 节点原样传递。请查看来自 Fuel 节点的错误消息定位根因。INVALID_URLprovider 域提供的 URL 无效时抛出。请确保 URL 合法。RESPONSE_BODY_EMPTYprovider 域服务器响应体为空时抛出。问题通常出在你所在环境到 RPC 之间的连接配置上请检查连接设置。UNSUPPORTED_FUEL_CLIENT_VERSION你访问的 Fuel 节点版本不被当前客户端支持时抛出。请检查 Fuel 节点版本并使用兼容的 SDK 版本去对接。ERROR_BUILDING_BLOCK_EXPLORER_URLchain 域当path、address、txId、blockNumber中同时传入了多个选项时抛出。请确保以上参数只传入一个。TIMEOUT_EXCEEDED见 4.1多出现于网络超时场景。4.4 钱包、账户与签名HD_WALLET_ERRORwallet 域硬件钱包HD wallet在不支持的配置下抛出具体是配置的哪一部分错误由错误消息决定——可能是公钥、私钥也可能是在配置/从扩展密钥转换时出错。WALLET_MANAGER_ERRORwallet 域钱包管理器因多种原因抛出具体由错误消息说明——例如口令passphrase不正确或钱包在管理器中不存在。MISSING_CONNECTORwallet 域同 4.2——请为Account或Wallet提供 connector。INVALID_PUBLIC_KEYwallet 域提供的公钥无效时抛出。请确保公钥有效。MISSING_PROVIDERprovider 域见 4.2。INSUFFICIENT_FUNDS_OR_MAX_COINSerrors 域见下文 4.7 详解。INVALID_PASSWORDwallet / account 域提供的密码不正确时抛出。请确保密码正确。INVALID_CREDENTIALScrypto 域提供的密码不正确时抛出凭据校验失败。请确保密码正确。4.5 助记词、种子与派生INVALID_MNEMONICmnemonic 域提供的助记词无效时抛出详情请阅读错误消息——常见原因是助记词短语的词数不在 12、15、18、21、24 这五个合法长度中。INVALID_CHECKSUMmnemonic 域助记词的校验和验证失败时抛出。请确保助记词正确。INVALID_ENTROPYmnemonic 域熵值不在 1632 字节之间或不是 4 的倍数时抛出。请确保熵值位于 1632 字节之间且是 4 的倍数。INVALID_SEEDmnemonic 域种子长度不在 1664 字节之间时抛出。请确保种子长度位于该区间。INVALID_WORD_LISTmnemonic 域词表长度不等于 2048 时抛出。提供给助记词生成的词表长度应恰好为 2048。INVALID_EVM_ADDRESSaddress 域提供的 EVM 地址无效时抛出。请确保 EVM 地址 合法。4.6 交易、Gas 与策略FUNDS_TOO_LOWtransaction 域账户资金低于所需金额时抛出。请确保账户有足够资金覆盖交易。INSUFFICIENT_FUNDS_OR_MAX_COINSerrors 域见 4.7。GAS_LIMIT_TOO_LOWtransaction 域gas limit 低于最小 gas limit 时抛出。请将 gas limit 提高到最小值以上。GAS_PRICE_TOO_LOWtransaction 域gas price 低于最小 gas price 时抛出。请将 gas price 提高到最小值以上。DUPLICATED_POLICYtransaction 域一笔交易中存在多个同类型 policy 时抛出。请确保交易的 policies 没有同类型重复项。INVALID_POLICY_TYPEtransaction 域为给定 Script 提供的 policy 类型非法时抛出。请确认该 policy 类型在PolicyType中定义。INVALID_TRANSACTION_INPUTtransaction 域输入类型非法时抛出。请确认类型在InputType范围内。INVALID_TRANSACTION_OUTPUTtransaction 域输出类型非法时抛出。请确认类型在OutputType范围内。INVALID_TRANSACTION_STATUStransaction 域节点返回的交易状态不符合预期时抛出。请确认收到的状态在TransactionStatus范围内。UNSUPPORTED_TRANSACTION_TYPEtransaction 域来自 Fuel 节点的交易类型不受支持时抛出。该类型应属于TransactionType枚举。INVALID_RECEIPT_TYPEreceipt 域receipt 类型非法时抛出。请确认类型在ReceiptType范围内。INVALID_CHUNK_SIZE_MULTIPLIERtransaction 域chunk size multiplier 不在 0 到 1 之间时抛出。请确保它是一个介于 0 和 1 之间的数字。ASSET_BURN_DETECTEDtransaction 域当你发送的交易将导致资产被销毁burn时抛出。请为交易添加相应的零钱币coin change输出或在交易请求中显式允许资产销毁。INVALID_TTLerrors 域TTL 小于等于 0 时抛出。请确保 TTL 是数字且大于 0。INVALID_CONFIGURABLE_CONSTANTS、CONTRACT_SIZE_EXCEEDS_LIMIT分别见 4.2。4.7 资源组装assembleTx、变更输出与 UTXO 限额以下错误码集中在「为交易收集与分配 coin 资源」阶段涉及 funding 操作、getResourcesToSpend与assembleTx等方法INSUFFICIENT_FUNDS_OR_MAX_COINSerrors 域在 funding 操作或调用getResourcesToSpend时可能抛出它对应两类问题Insufficient Balance余额不足指定账户的余额不足以覆盖所需金额UTXO Limit ExceededUTXO 超限账户总资金充足但资金分散在过多的 UTXOcoin中。区块链会限制单笔交易可使用的 UTXO 数量超出该限制会导致交易无法被处理。排查步骤先查询 该assetId的余额 确认账户资金是否足够从而定位真实原因。解决方式若为余额不足请获取足够的所需资产若为 UTXO 超限请通过合并 UTXO 减少数量以满足网络要求可参考 合并 UTXO 指南。MAX_INPUTS_EXCEEDEDtransaction 域交易输入数量超过区块链允许的上限时抛出。请减少输入数量典型做法仍是合并 UTXO 或精简转账项。MAX_OUTPUTS_EXCEEDEDtransaction 域交易输出数量超过区块链允许的上限时抛出。CHANGE_OUTPUT_COLLISIONtransaction 域当交易请求中指定的零钱输出与assembleTx参数指定的零钱输出发生冲突时抛出冲突的判定分两步1) 交易请求已为某个资产 ID 与地址设置了零钱输出2)assembleTx参数为同一资产 ID指定了一个不同的零钱输出。解决方式是保证两处配置一致。DUPLICATE_CHANGE_OUTPUT_ACCOUNTtransaction 域assembleTx的accountCoinQuantities参数中同一资产 ID 出现多个不同changeOutputAccount的重复条目时抛出1)accountCoinQuantities对同一资产 ID 含有多条记录2) 这些记录对同一资产 ID 指定了不同的changeOutputAccount。解决方式是合并为单一且一致的配置。ERROR_BUILDING_BLOCK_EXPLORER_URL见 4.3。4.8 fuels CLI配置文件与工作区以下错误码与 fuels CLIfuels命令的配置解析、初始化流程相关CONFIG_FILE_NOT_FOUND找不到配置文件时抛出。配置文件既可能是fuels.config.[ts|js|mjs|cjs]也可能是 TOML 文件。请确保配置文件位于项目根目录。CONFIG_FILE_ALREADY_EXISTS项目根目录已存在配置文件时抛出。一个项目只能运行一次fuels init若需重新初始化请先删除现有配置文件或直接修改它。WORKSPACE_NOT_DETECTED在错误消息指出的目录中检测不到 workspace如 Sway Forc workspace时抛出。请确保 workspace 存在于指定目录。MISSING_REQUIRED_PARAMETERerrors 域某方法缺少必填参数时抛出具体缺失项由错误消息说明——典型场景是类型生成时既未提供inputs也未提供filepaths两者至少需要一个。4.9 兜底UNKNOWNUNKNOWNUnknown 域当错误尚未被映射到具体错误码时使用此兜底码。如果你认为自己发现了 bug可向 fuels-ts 官方提交 issue附上错误信息与复现步骤供团队排查。五、错误码与你代码之间的三类典型关系纵观上文手册可以把错误码的用途归纳为三种典型关系便于你在架构设计时分类对待直接可恢复面向用户提示如INSUFFICIENT_FUNDS_OR_MAX_COINS、FUNDS_TOO_LOW、GAS_LIMIT_TOO_LOW、GAS_PRICE_TOO_LOW。它们几乎总是由用户的余额、参数配置不足引起适合在 UI 层翻译成明确的操作指引并配合 余额查询、合并 UTXO 等引导。面向开发调试多为编程期错误如 ABI 相关的JSON_ABI_ERROR、TYPE_NOT_FOUND、FUNCTION_NOT_FOUND以及 CLI 配置相关的CONFIG_FILE_NOT_FOUND。它们通常暴露的是类型生成、合约 ABI 或工程配置问题最有效的做法是携带code message metadata打日志并在本地复现。运行时环境相关如INVALID_REQUEST、NODE_INFO_CACHE_EMPTY、TIMEOUT_EXCEEDED、UNSUPPORTED_FUEL_CLIENT_VERSION、RESPONSE_BODY_EMPTY。它们与 Fuel 节点版本、网络连通性、RPC 服务配置强相关需要在重试、切换节点、核对 SDK 与节点版本兼容性等层面处理。六、总结FuelError是 fuels-ts 面向调用方提供的统一异常出口fuel-error.ts 与 error-codes.ts 构成了它的实现底座前者定义了携带code、metadata、rawError、VERSIONS的错误对象及parse/toObject等能力后者以枚举形式固化了全部错误码并按其字符串值在运行时暴露。开发者在接住 SDK 错误后正确的下一步不是「读堆栈猜原因」而是先读err.code——对照本手册找到触发条件与官方建议的解决路径需要精确断言时可借助 expect-to-throw-fuel-error.ts 这类测试工具把「错误必须携带指定code」变成可自动验证的回归约束。这套「统一类 枚举码 文档手册」的机制正是 fuels-ts 让复杂链上开发保持可排错性的关键设计之一。【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考