Dagger TypeScript SDK 错误码全解：ERROR_CODES（D100–D110）识别与处理实战指南

Dagger TypeScript SDK 错误码全解ERROR_CODESD100–D110识别与处理实战指南【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger本文围绕 Dagger版本 0.20TypeScript SDK 中导出的ERROR_CODES常量系统梳理该 SDK 内置的 11 个错误码D100–D110与对应错误类之间的映射关系并结合仓库源码说明每个错误的触发场景、携带的附加字段以及推荐的捕获与定位方式。读完本文你将能够用instanceof或error.code快速识别 Dagger SDK 抛出的任意错误并在真实 CI/CD 管道中对引擎会话、GraphQL 查询、容器执行等环节的异常进行精准排障。从ERROR_CODES变量说起ERROR_CODES是dagger.io/daggerTypeScript SDK 中导出的一组只读常量对象它把每个 Dagger 专用错误类与一个稳定的字符串错误码一一对应。该变量的完整 API 参考页位于 ERROR_CODES.md其类型声明为 const **ERROR_CODES**: object在源码层面该对象定义于 errors-codes.ts使用as const断言保证每个属性都是字面量类型从而让 TypeScript 能对错误码进行精确的类型推导export const ERROR_CODES { GraphQLRequestError: D100, UnknownDaggerError: D101, TooManyNestedObjectsError: D102, EngineSessionConnectParamsParseError: D103, EngineSessionConnectionTimeoutError: D104, EngineSessionError: D105, InitEngineSessionBinaryError: D106, DockerImageRefValidationError: D107, NotAwaitedRequestError: D108, ExecError: D109, IntrospectionError: D110, } as const同一个文件中还基于ERROR_CODES的键派生出了ERROR_NAMES映射键名到键名的同构对象以及两个辅助类型ErrorNames所有错误类名的联合类型ErrorCodes所有错误码字符串的联合类型。各个错误类正是通过ERROR_NAMES.XxxError和ERROR_CODES.XxxError来声明自己的name与code字段从而实现错误码与错误类双向可查。错误码总览D100 到 D110 完整映射表参考文档完整列出了 11 个错误码下表为全量对照说明依据各错误类源码中的注释整理错误码错误类类名触发场景概述D100GraphQLRequestError引擎在执行过程中抛出错误并通过 GraphQL 返回D101UnknownDaggerErrorSDK 无法识别错误仅包装原始causeD102TooManyNestedObjectsError引擎返回了多于一个的响应值D103EngineSessionConnectParamsParseError无法从 session 二进制输出中解析连接参数D104EngineSessionConnectionTimeoutError会话连接超时无法解析所需端口D105EngineSessionError在读到任何有效端口前遭遇 EOF通常意味着无法建立连接D106InitEngineSessionBinaryError无法把 dagger 二进制从镜像复制到本地主机D107DockerImageRefValidationError传入的镜像引用未通过校验不符合镜像构造器要求D108NotAwaitedRequestErrorcompute 函数未被awaitD109ExecError管道中 exec 操作返回的 API 错误D110IntrospectionError内省introspection查询出错这些错误类都在 sdk/typescript/src/common/errors 目录下各有一个独立文件实现并通过 index.ts 统一对外导出。注意EngineSessionError类本身实现在EngineSessionErrorOptions.ts文件中该文件同时导出了其选项类型这一点从 index.ts 的export { EngineSessionError } from ./EngineSessionErrorOptions.js可以确认。错误的基石DaggerSDKError基类所有上述错误类都继承自抽象基类DaggerSDKError见 DaggerSDKError.ts因此它们共享一套统一的结构化接口export abstract class DaggerSDKError extends Error { /** 错误类名如 GraphQLRequestError */ abstract readonly name: ErrorNames /** Dagger 专用错误码用于以编程方式识别错误 */ abstract readonly code: ErrorCodes /** 导致该错误的原始错误 */ cause?: Error protected constructor(message: string, options?: DaggerSDKErrorOptions) { super(message) this.cause options?.cause } printStackTrace() { ... } }关键设计点code字段是编程识别的官方途径基类注释明确写道 Use this to identify dagger errors programmatically即不要依赖脆弱的字符串匹配而应直接比较error.code与ERROR_CODES中的值cause保留原始错误所有子类构造函数都接受DaggerSDKErrorOptions可选cause便于错误链溯源printStackTrace()内置调试方法通过log(this.stack)输出堆栈方便在交互式脚本中快速排查Symbol.toStringTag返回name保证String(err)与类型转换时的可读性。引擎会话类错误D103–D106连接与初始化阶段这组错误集中在 SDK 与 Dagger 引擎建立会话的阶段对应源码位于 sdk/typescript/src/common/errors 目录及会话启动逻辑 sdk/typescript/src/provisioning/bin.ts。EngineSessionConnectParamsParseErrorD103当 SDK 无法从会话二进制的输出中解析出建立连接所需的参数时抛出。它携带一个专有字段parsedLine: string导致解析失败的那一行内容便于诊断输出格式异常。EngineSessionConnectionTimeoutErrorD104当解析所需端口的过程因连接超时而失败时抛出。专有字段timeOutDuration: number超时发生时已经过的毫秒数。EngineSessionErrorD105当在读到任何有效端口之前就遭遇 EOF 时抛出通常意味着无法建立连接源码注释原话。它没有额外专有字段message与cause足以描述问题。InitEngineSessionBinaryErrorD106当 dagger 二进制无法从 dagger 镜像复制到本地主机时抛出见 bin.ts 附近的抛出点。常见诱因包括镜像拉取失败、文件系统权限不足、磁盘空间不足等。GraphQL 查询类错误D100–D102请求与响应异常这组错误与 SDK 向引擎发送 GraphQL 查询、处理响应的环节相关核心抛出逻辑集中在 compute_query.ts。GraphQLRequestErrorD100这是最引擎原生的错误引擎在执行查询时抛出了错误并通过 GraphQL 响应回传。它额外暴露三个调试字段见 GraphQLRequestError.tsrequestContext导致错误的查询query与变量variablesresponse包含错误的 GraphQL 响应体extensions首个 GraphQL 错误的扩展信息response.errors[0]?.extensions引擎常在此携带附加的排障元数据。UnknownDaggerErrorD101当 SDK 无法识别底层错误的类型、只能将原始错误包装为cause时抛出见 UnknownDaggerError.ts。它相当于错误体系中的兜底分支任何未匹配到具体语义的错误都会落到这里。TooManyNestedObjectsErrorD102Dagger 引擎对一次查询只期望返回一个响应值当引擎返回了多个值时抛出见 TooManyNestedObjectsError.ts。专有字段response包含多个值的原始响应。执行、校验与响应类错误D107–D110业务操作异常DockerImageRefValidationErrorD107当传入的镜像引用未通过校验、不符合镜像构造器DockerImage constructor要求时抛出见 DockerImageRefValidationError.ts。专有字段ref: string触发错误的镜像引用字符串直接用于定位拼写或格式问题。NotAwaitedRequestErrorD108当 compute 函数未被await时抛出见 NotAwaitedRequestError.ts。这是 TypeScript/JavaScript 异步模型下典型的忘写 await编程错误错误信息会指导你补上await。ExecErrorD109管道中 exec 操作失败时的标准 API 错误见 ExecError.ts也是容器构建/测试场景中最常见的错误之一。它携带完整的命令执行上下文cmd: string[]导致错误的命令参数数组形式exitCode: number命令的退出码stdout: string命令的标准输出stderr: string命令的标准错误输出extensions?GraphQL 错误扩展信息。IntrospectionErrorD110与 schema 内省introspection相关的错误见 IntrospectionError.ts通常在 SDK 获取或解析引擎 schema 定义时出现。源码视角这些错误在哪里被抛出为了印证上述分类下面列出仓库中几处典型的抛出点读者可在对应文件中直接查看抛出时的上下文理解什么条件下会走到哪个分支compute_query.ts 是 GraphQL 响应处理的错误分发枢纽依次覆盖了响应嵌套对象数量异常 →TooManyNestedObjectsError引擎返回 GraphQL 错误 →ExecError当错误来自 exec 操作或GraphQLRequestError请求未被 await →NotAwaitedRequestError其余无法识别的情况 →UnknownDaggerError。bin.ts 是会话引导逻辑覆盖了InitEngineSessionBinaryError、EngineSessionConnectParamsParseError与EngineSessionError的抛出场景registry.ts 中模块注册失败会包装为UnknownDaggerError。在代码中识别与捕获 Dagger 错误由于所有错误都继承自DaggerSDKError推荐用两种互补方式识别错误。方式一类型判断推荐用于精确处理import { connect, ExecError, GraphQLRequestError, ERROR_CODES } from dagger.io/dagger try { await connect(async (client) { const out await client .container() .from(node:20) .withExec([sh, -c, exit 1]) .stdout() console.log(out) }) } catch (err) { if (err instanceof ExecError) { console.error(命令 ${err.cmd.join( )} 失败) console.error(退出码: ${err.exitCode}) console.error(stdout: ${err.stdout}) console.error(stderr: ${err.stderr}) } else if (err instanceof GraphQLRequestError) { console.error(引擎返回 GraphQL 错误:, err.response.errors) console.error(原始请求:, err.requestContext) } else { console.error(未知 Dagger 错误:, err) } }方式二比较error.code推荐用于通用日志与监控基类文档明确建议把code作为编程识别的稳定标识import { connect, ERROR_CODES, DaggerSDKError } from dagger.io/dagger try { // ... 执行任意 Dagger 操作 } catch (err) { if (err instanceof DaggerSDKError) { switch (err.code) { case ERROR_CODES.ExecError: console.error(Exec 失败${err.code}) break case ERROR_CODES.EngineSessionConnectionTimeoutError: console.error(引擎会话连接超时${err.code}) break default: console.error(Dagger 错误 ${err.code}: ${err.name} - ${err.message}) } } }实践建议先按错误码分门别类记录日志再针对高频错误尤其是D109 ExecError与D100 GraphQLRequestError定制诊断信息引擎会话类错误D103–D106多为环境问题检查网络、Docker 守护进程、引擎镜像可拉取性以及磁盘空间D108 NotAwaitedRequestError是纯代码问题检查是否漏写awaitD107 DockerImageRefValidationError时检查ref字段中的镜像名与 tag 格式。版本化文档中的位置与延伸阅读本主题的 API 参考页位于版本化文档目录 version-0.20/reference/typescript/common/errors/variables/ERROR_CODES.md与之一同维护的还有各错误类的独立参考页位于同目录的classes/子目录。仓库中还保留了多版本的历史文档见 docs/versioned_docs对比不同版本的错误码表可以了解 SDK 错误体系的演进。若想深入阅读源码推荐按以下顺序errors-codes.ts错误码与错误名的完整定义DaggerSDKError.ts所有错误的基类index.ts错误体系的统一出口compute_query.ts 与 bin.ts两类主要抛出场景的现场。掌握ERROR_CODES这张错误码 ↔ 错误类的映射表是快速定位 Dagger TypeScript SDK 运行问题的第一步一旦异常被抛出先看err.code落在哪个区间D100–D102 查询响应、D103–D106 引擎会话、D107–D110 业务操作再按对应错误类的专有字段展开排查即可把排障时间压缩到最低。【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考