isomorphic-git 错误码全指南：从 Error Codes 索引到源码级排查实战

开发工具【免费下载链接】isomorphic-gitA pure JavaScript implementation of git for node and browsers!项目地址https://gitcode.com/gh_mirrors/is/isomorphic-git点击查看免费下载isomorphic-git 是一套纯 JavaScript 实现的 Git 库可在 Node.js 与浏览器中运行。当各类 git 操作clone、fetch、push、checkout、commit 等失败时它会抛出带有稳定code标识的错误对象。本文以仓库中 errors.mdversion-0.70.7 的 Error Codes 索引为骨架结合 src/errors 目录下的真实实现与 test-GitError.js 测试用例系统梳理每个错误码的触发场景、参数占位符含义与常见处置方案帮助你在业务代码中按错误码精确分支处理快速定位故障根因。一、错误码机制stable code、data 与序列化错误对象从哪来在isomorphic-git中所有 API 命令抛出的错误都继承自 src/errors/BaseError.js 中的BaseError它扩展了原生Errorexport class BaseError extends Error { constructor(message) { super(message) this.caller } toJSON() { return { code: this.code, data: this.data, caller: this.caller, message: this.message, stack: this.stack, } } get isIsomorphicGitError() { return true } }每个具体错误类都遵循同一套模式构造函数接收若干语义化参数拼装出人类可读的message同时把结构化信息写入this.data并通过静态属性声明稳定错误码例如 CheckoutConflictError.jsCheckoutConflictError.code CheckoutConflictError因此每个错误类都有三个可靠的信息来源err.code与类名一致的稳定字符串是程序分支判定的首选依据err.data携带触发错误的上下文数据如冲突文件列表、HTTP 状态码、OID 等err.message面向人类阅读的完整描述文本err.isIsomorphicGitError恒为true用于区分库自身错误与其他异常。为什么用 code 而不是 message 做判断错误消息文本在版本演进中可能调整措辞对比本页 version-0.70.7 与 当前 docs 中的 alphabetic 索引 可见部分消息已变化而code作为契约保持稳定。这一点也被测试明确守护tests/test-GitError.js 遍历所有错误类断言「类名 静态 code」确保不会出现错配。错误如何跨进程/跨请求传递BaseError提供了toJSON()与fromJSON()将错误序列化为{ code, data, caller, message, stack }结构再反序列化为BaseError实例。这意味着在浏览器 Worker、Node 子进程或服务端日志之间传递错误时可以保留code与data而不丢失关键诊断信息。二、按功能域速查错误码总览与触发场景version-0.70.7 的 errors.md 共列出 68 个错误码。为便于检索本文按触发域将其归类如下消息中的{占位符}为实际注入的动态值。1. 锁文件与并发安全错误码消息模板触发场景AcquireLockFileFailUnable to acquire lockfile { filename }. Exhausted tries.多次尝试后仍无法获取.git/index.lock等锁文件常见于多个进程并发写仓库DoubleReleaseLockFileFailCannot double-release lockfile { filename }.对同一锁文件重复释放说明锁管理逻辑被调用了两次从仓库结构看锁机制封装在 src/utils/lock.js由 src/managers/GitIndexManager.js 等管理器在读写 index 时调用用于保证对同一仓库的写操作串行化。如果你的程序用 worker 并发执行写操作需要注意同一仓库目录不能同时被两个进程写入。2. 参数校验与调用契约错误码消息模板触发场景MissingRequiredParameterErrorThe function { function } requires a { parameter } parameter but none was provided.调用 API 时缺少必需参数如未传fs、dir、ref。对应实现见 MissingParameterError.jsdata.parameter指出缺的是哪个参数InvalidParameterCombinationErrorThe function { function } doesnt take these parameters simultaneously: { parameters }同时传入了互斥参数如username/password与oauth2format混用DirectorySeparatorsErrorfilepath parameter should not include leading or trailing directory separators ...文件路径参数含首尾/或\在某些平台会导致解析异常InvalidDepthParameterErrorInvalid value for depth parameter: { depth }depth参数不是合法数值应为正整数MissingUsernameError/MissingPasswordTokenError/MissingTokenErrorMissing username / Missing password or token / Missing token认证所需字段缺失参数校验的通用逻辑集中在 src/utils/assertParameter.js各 API 入口src/api在调用底层命令前先做参数断言。3. 引用Ref操作错误码消息模板触发场景RefExistsErrorFailed to create { noun } { ref } because { noun } { ref } already exists.创建分支/标签时目标 ref 已存在RefNotExistsErrorFailed to { verb } { noun } { ref } because { noun } { ref } does not exists.删除/重命名不存在的 refInvalidRefNameErrorFailed to { verb } { noun } { ref } because that name would not be a valid git reference. A valid alternative would be { suggestion }.ref 名不合法错误还附带了合法替代名建议对应实现见 InvalidRefNameError.jsMismatchRefValueErrorProvided oldValue doesnt match the actual value of { ref }.writeRef传入oldValue校验失败CAS 语义ResolveRefErrorCould not resolve reference { ref }.无法把 ref 解析为 OIDExpandRefErrorCould not expand reference { ref }.缩写 ref如main无法唯一展开BranchDeleteErrorFailed to delete branch { ref } because branch { ref } checked out now.尝试删除当前已检出的分支NoHeadCommitErrorFailed to create { noun } { ref } because the HEAD ref could not be resolved to a commit.HEAD 无法解析到提交创建分支等操作失败ref 解析的底层实现在 src/managers/GitRefManager.js它同时处理 loose refs 与 packed-refsGitPackedRefs.js。4. 对象存储Object 读写错误码消息模板触发场景ReadObjectFailFailed to read git object with oid { oid }按 OID 读取对象失败NotAnOidFailExpected a 40-char hex object id but saw { value }.传入的 OID 不是 40 位十六进制字符串ShortOidNotFoundCould not find an object matching { short }.缩写 OID 找不到对应对象AmbiguousShortOidFound multiple oids matching { short } ({ matches }). Use a longer abbreviation length to disambiguate them.缩写 OID 命中多个对象需要更长缩写实现见 AmbiguousError.jsCorruptShallowOidFailnon-40 character shallow oid: { oid }shallow 文件中出现非法 OIDObjectTypeUnknownFailObject { oid } has unknown type { type }.对象类型非法非 blob/commit/tree/tagObjectTypeAssertionFailObject { oid } was anticipated to be a { expected } but it is a { type }. This is probably a bug deep in isomorphic-git!对象类型与预期不符实现见 ObjectTypeError.jsObjectTypeAssertionInPathFailFound a blob { oid } in the path { path } where a tree was expected.路径遍历时遇到 blob 而非 treeObjectTypeAssertionInRefFail{ ref } is not pointing to a { expected } object but a { type } object.ref 指向的对象类型与命令预期不符ObjectTypeAssertionInTreeFailObject { oid } in tree for { entrypath } was an unexpected object type { type }.tree 条目中的对象类型异常对象读取链路从 src/storage/readObject.js 进入先查 loose objectsreadObjectLoose.js再查 packfilereadObjectPacked.js。5. 路径与工作区文件错误码消息模板触发场景FileReadErrorCould not read file { filepath }.工作区文件读取失败GitRootNotFoundErrorUnable to find git root for { filepath }.向上查找.git目录失败TreeOrBlobNotFoundErrorNo file or directory found at { oid }:{ filepath }.指定 OID 与路径下不存在文件或目录DirectoryIsAFileErrorUnable to read { oid }:{ filepath } because encountered a file where a directory was expected.遍历时文件与目录冲突文件系统抽象层由 src/models/FileSystem.js 提供git root查找逻辑在 src/utils/discoverGitdir.js。6. 网络、HTTP 与传输协议错误码消息模板触发场景HTTPErrorHTTP Error: { statusCode } { statusMessage }服务器返回非 200 状态data中会携带statusCode、statusMessage与response响应体实现见 HttpError.jsEmptyServerResponseFailEmpty response from git server.服务器返回空响应UnparseableServerResponseFailUnparsable response from server! Expected unpack ok or unpack [error message] but received { line }.push 响应中unpack行无法解析AssertServerResponseFailExpected { expected } but got { actual }.服务器响应内容与协议预期不符RemoteDoesNotSupportSmartHTTPRemote did not reply using the smart HTTP protocol. Expected 001e# servicegit-upload-pack but received: { preview }远端不支持 smart HTTP 协议如纯 dumb HTTP 服务器RemoteDoesNotSupportShallowFail/RemoteDoesNotSupportDeepenSinceFail/RemoteDoesNotSupportDeepenRelativeFail/RemoteDoesNotSupportDeepenNotFailRemote does not support shallow fetches / by date / relative ...远端能力不支持对应的浅克隆shallow fetch类型RemoteUrlParseErrorCannot parse remote URL: { url }远端 URL 无法解析对应实现为 UrlParseError.jsUnknownTransportErrorGit remote { url } uses an unrecognized transport protocol: { transport }传输协议不受支持实现见 UnknownTransportError.js网络层实现在 src/managers/GitRemoteHTTP.js它负责 HTTP 传输、smart 协议握手# servicegit-upload-pack应答与 pkt-line 解析。7. 认证与凭据错误码消息模板触发场景MissingUsernameErrorMissing username需要用户名但未提供MissingTokenErrorMissing token需要 token 但未提供MissingPasswordTokenErrorMissing password or token密码与 token 均未提供MixUsernamePasswordTokenErrorCannot mix username and password with token同时传了username/password与tokenMixPasswordTokenErrorCannot mix password with token同时传了password与tokenMixPasswordOauth2formatMissingTokenError/MixPasswordOauth2formatTokenErrorCannot mix password with oauth2format. Missing token. / ... and tokenpassword与oauth2format混用MixUsernameOauth2formatMissingTokenError/MixUsernameOauth2formatTokenErrorCannot mix username with oauth2format. ...username与oauth2format混用MixUsernamePasswordOauth2formatMissingTokenError/MixUsernamePasswordOauth2formatTokenErrorCannot mix username and password with oauth2format. ...用户名密码与oauth2format混用UnknownOauth2FormatI do not know how { company } expects its Basic Auth headers to be formatted for OAuth2 usage. ...未知的 OAuth2 服务商格式这组错误提示了一个重要设计username/password、token、oauth2format三套认证参数互相排斥。使用指南可参考 authentication.mdversion-0.70.7 与 docs/onAuth.md推荐用onAuth回调动态返回认证凭据。8. 推送Push服务端拒绝错误码消息模板触发场景PushRejectedNonFastForwardPush rejected because it was not a simple fast-forward. Use force: true to override.推送被拒非快进合并可用force: true强制覆盖PushRejectedTagExistsPush rejected because tag already exists. Use force: true to override.推送的标签已存在同样可用force: true覆盖两个错误对应 PushRejectedError.js 中的not-fast-forward与tag-exists两种reason。注意强制推送会改写远端历史仅应在确认安全时使用。9. 合并、检出与提交状态错误码消息模板触发场景CheckoutConflictErrorYour local changes to the following files would be overwritten by checkout: { filepaths }检出会覆盖本地未提交修改data.filepaths为冲突文件列表见 CheckoutConflictError.jsCommitNotFetchedErrorFailed to checkout { ref } because commit { oid } is not available locally. Do a git fetch ...目标提交本地不存在需先 fetchFastForwardFailA simple fast-forward merge was not possible.无法进行快进合并如fastForwardOnly: true时MergeNotSupportedFailMerges with conflicts are not supported yet.产生冲突的合并暂不支持0.70.x 时代的能力边界NoRefspecConfiguredErrorCould not find a fetch refspec for remote { remote }. ...远端缺少 fetch refspec 配置消息中会给出应补充的 config 片段示例MaxSearchDepthExceededMaximum search depth of { depth } exceeded.递归搜索如 findRoot 向上遍历超出最大深度其中NoRefspecConfiguredError的提示信息非常实用——它会直接建议你在 config 中补充[remote { remote }] fetch refs/heads/*:refs/remotes/origin/*10. 插件系统错误码消息模板触发场景CoreNotFoundNo plugin core with the name { core } is registered.未注册指定名称的 corePluginUndefinedA command required the { plugin } plugin but it was undefined.命令依赖的插件fs/http/credentialManager等未提供PluginUnrecognizedUnrecognized plugin type { plugin }插件类型无法识别PluginSchemaViolationSchema check failed for { plugin } plugin; missing { method } method.插件缺少必需的方法不满足插件接口契约插件机制通过 src/managers/index.js 注册与校验浏览器端必须显式提供fs与http插件详见 guide-fs.mdversion-0.70.7。11. 其他内部与通用错误错误码消息模板触发场景InternalFailAn internal error caused this command to fail. Please file a bug report at ...库内部异常通常伴随 bug需要上报NotImplementedFailTODO: { thing } still needs to be implemented!调用了尚未实现的功能AddingRemoteWouldOverwriteAdding remote { remote } would overwrite the existing remote. Use force: true to override.addRemote覆盖已有远端用force: true覆盖ResolveCommitErrorCould not resolve { oid } to a commit.OID 无法解析为 commit 对象ResolveTreeErrorCould not resolve { oid } to a tree.OID 无法解析为 tree 对象三、实战按错误码编写分支处理代码1. 通过Errors命名空间导入错误类isomorphic-git 从顶层导出Errors命名空间src/index.js可以直接导入并按类判断import git, { Errors } from isomorphic-git try { await git.checkout({ fs, dir, ref: feature-branch }) } catch (err) { if (err instanceof Errors.CheckoutConflictError) { console.error(以下文件有本地修改将被覆盖, err.data.filepaths) } else if (err instanceof Errors.CommitNotFetchedError) { console.error(提交不存在请先 fetch, err.data.oid) } else if (err instanceof Errors.HttpError) { console.error(HTTP ${err.data.statusCode} ${err.data.statusMessage}) } else { throw err } }注意 errors/index.js当前源码 与 0.70.7 的错误类集合并不完全一一对应——如CheckoutConflictError、CommitNotFetchedError、HttpError、PushRejectedError等核心类在两条版本线上都存在而部分*Fail风格的旧错误名在后续版本中已被重构为*Error命名。以当前安装版本实际导出的Errors为准。2. 兜底记录完整错误信息无法精确匹配时应记录序列化后的完整错误避免丢失code与data} catch (err) { if (err.isIsomorphicGitError err.toJSON) { console.error(JSON.stringify(err.toJSON(), null, 2)) } else { console.error(err) } }toJSON()输出形如{ code: NotFoundError, data: { what: foobar.txt }, caller: , message: Could not find foobar.txt., stack: ... }这正是 test-GitError.js 中断言的序列化结构。四、常见故障排查速查表报错场景典型错误码首要排查动作检出时本地修改将被覆盖CheckoutConflictError查看data.filepaths提交或丢弃对应修改目标提交本地没有CommitNotFetchedError先执行fetch再checkout推送被拒绝PushRejectedNonFastForward/PushRejectedTagExists先pull合并确需覆盖时显式传force: trueHTTP 层失败HTTPError检查data.statusCode、statusMessage与response排查 URL、鉴权与网络远端不支持 smart HTTPRemoteDoesNotSupportSmartHTTP确认服务器如 gogs/gitea 等开启 git smart HTTP 支持缺少必需参数MissingRequiredParameterError依据data.parameter补传参数缩写 OID 不唯一AmbiguousShortOid加长 OID 缩写长度ref 名非法InvalidRefNameError按data.suggestion使用合法替代名认证参数混用Mix*系列只保留username/password、token、oauth2format三者之一五、写在最后错误码的演进与使用建议以code为程序判据消息文本可能随版本变化code才是稳定契约test-GitError.js 保证类名与 code 一致。充分读取data多数错误把结构化上下文放入data如冲突文件、HTTP 状态、OID、ref 名比解析message更可靠。0.70.7 属于较旧版本线部分*Fail命名如AcquireLockFileFail、ReadObjectFail在后续版本中已更名或合并迁移到新版时需按新导出的Errors重新适配。区分错误等级InternalFail与ObjectTypeAssertionFail提示库内部缺陷应升级库或上报 issueCheckoutConflictError、PushRejectedNonFastForward等则是业务可恢复错误应在应用层友好处理。如果需要在浏览器环境使用请先配置fs与http插件并阅读 guide-quickstart.mdversion-0.70.7 与 guide-fs.mdversion-0.70.7命令行场景可参考 guide-cli.mdversion-0.70.7。掌握这套错误码体系你的 isomorphic-git 应用就能做到报错即定位、分支即处理。赞分享开发工具【免费下载链接】isomorphic-gitA pure JavaScript implementation of git for node and browsers!项目地址https://gitcode.com/gh_mirrors/is/isomorphic-git点击查看免费下载相关推荐StarRocks 错误码Error Codes完整参考与排查指南StarRocks 错误码Error Codes完整参考与排查指南 StarRocks 对外通过 MySQL 兼容协议提供查询服务因此查询请求失败时会返回数据库OLAP数据仓库大数据湖仓一体数据分析InspireFace 错误反馈码Error Feedback Codes完整指南错误码表、数值结构与跨语言排查实践InspireFace 错误反馈码Error Feedback Codes完整指南错误码表、数值结构与跨语言排查实践 本文以 Error Feedback人工智能计算机视觉深度学习CANN Runtime Profiling 错误码EK 系列排查指南从错误信息到源码级定位CANN Runtime Profiling 错误码EK 系列排查指南从错误信息到源码级定位 导读 本文聚焦 CANN Runtime 中 ProfiliCANNAscend人工智能性能剖析系统编程上一篇Guardrails安全审计LLM应用合规性检查清单下一篇Flet GitHubOAuthProvider 权威指南用 Python 实现 GitHub OAuth 登录创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考