For AI agents: the complete documentation index is available at https://devcodex-labs.github.io/capability-graph/llms.txt, the full documentation bundle is available at https://devcodex-labs.github.io/capability-graph/llms-full.txt, and this page is available as Markdown at https://devcodex-labs.github.io/capability-graph/reference/errors.md.
Capability Graph

错误与恢复动作

可用

CapabilityGraphError 提供 code、稳定默认 message、nextAction 和可选的有限 details。Adapter 内部异常不会原样暴露私有路径或对象。

完整错误语义由声明提取器与受检数据共同生成：每个公开 ErrorCode 都必须具有含义、常见触发、典型 NextAction 和调用方处理方式。排错路径见 故障排查。

完整错误语义

下表覆盖公开 ErrorCode 全集。典型动作帮助调用方选路，具体处理始终以错误实例的 nextAction 为准。

ErrorCode含义常见触发典型 NextAction调用方处理
CG_CONFIG_INCOMPLETE核心配置缺失或字段无效。Provider、预算或必需后端配置未满足启动条件。configure_backend补齐配置并重新创建 CapabilityGraph 实例。
CG_DUAL_AUTHORITY同一 Provider 配置了多个权威来源。Provider 配置重复，无法确定唯一静态定义来源。configure_backend每个 providerId 只保留一个 authority 后重新初始化。
CG_SCOPE_DENIED请求超出 Effective Provider Scope。查询、结果或 Provider 不在主机与集成共同允许的范围内。narrow_scope收窄请求到已授权 Provider；不要绕过 Scope 校验。
CG_IDENTITY_AMBIGUOUS能力身份缺少唯一 Provider 上下文。多 Provider 查询只提供 capabilityId，无法构成完整身份。fix_input补充 providerId，使用完整 CapabilityRef 重试。
CG_IDENTITY_INVALIDProvider、Capability 或 Knowledge 身份格式无效。ID 不符合公开格式，或来源定义中出现非法身份。fix_input调用方输入应修正后重试；若 details 指向来源定义，则修复来源。
CG_NOT_FOUND请求的 Provider、Capability、Knowledge 或 Runtime 修订不存在。完整身份在当前可读视图中没有匹配项。fix_input校正身份，或先调用列表/发现接口获取当前可用项。
CG_VALIDATION_FAILED静态来源定义未通过验证。Schema、哈希、端点或其他图约束不成立。repair_source根据有限 details 修复权威来源，再执行刷新。
CG_RELATION_CROSS_PROVIDER图关系跨越了 Provider 边界。parents、specializes 或 related 指向其他 Provider。repair_source把关系端点改为同一 Provider 内的能力身份。
CG_RELATION_CYCLE分类或特化关系形成环。parents、specializes 或 requires 的独立全图验证发现环。repair_source调整关系方向或移除闭环边，再刷新来源。
CG_LOAD_FAILEDProvider 权威来源加载失败。文件、数据库扫描或视图清理无法完成。repair_source检查来源可读性与后端状态；恢复后重新加载。
CG_NO_ACTIVE_VIEW当前没有已验证且可读的 Provider 视图。实例已关闭，或刷新失败且不存在可继续服务的旧视图。refresh恢复来源后刷新；实例已关闭时创建新实例。
CG_REVISION_MISMATCH请求的修订或游标不再对应当前可读视图。分页、检索或 Runtime 请求携带了过期修订。refresh放弃旧游标，从首个请求重新获取当前修订。
CG_INDEX_STALE检索索引与当前来源身份不一致。Retriever 返回的来源修订或能力身份已过期。refresh刷新或重建索引，再从新的发现请求开始。
CG_INPUT_INVALID查询参数或参数组合无效。必需字段缺失、游标非法或互斥参数同时出现。fix_input修正输入；以错误实例携带的 nextAction 为最终准则。
CG_RUNTIME_CONTEXT_REQUIREDRuntime 查询缺少项目或环境上下文。未提供非空 project 与 environment。fix_input同时补充项目和环境，再发起 Runtime 查询。
CG_RUNTIME_DISABLEDProvider 未启用 Runtime Adapter。对只有静态能力的 Provider 发起 Runtime 查询。configure_backend配置 Runtime Adapter，或停止对该 Provider 请求运行态。
CG_RUNTIME_UNAVAILABLERuntime 来源当前不可用。Adapter 抛错、超时或无法取得运行态快照。repair_source检查运行态服务与 Adapter；恢复后按策略重试。
CG_RUNTIME_RESULT_MISMATCHRuntime 结果与请求上下文不匹配。实例的 project、environment 或关联身份不符合请求。fix_input先核对请求上下文；若输入正确则修复 Adapter 映射。
CG_ADAPTER_CONTRACT_INVALIDAdapter 返回值违反公开合同。分页、身份、内容哈希或结果结构不满足约束。repair_source修复 Adapter 实现；不要在调用方猜测或补造缺失字段。
CG_KNOWLEDGE_NOT_ASSOCIATED所选能力没有关联知识。能力存在，但其知识引用集合为空或目标未关联。repair_source为能力补充知识引用，或改选具有知识关联的能力。
CG_KNOWLEDGE_TYPE_UNSUPPORTED该知识类型不支持直接读取。例如对 collection 类型调用 readDocuments。use_retrieval切换到知识检索接口，再按返回目标读取具体文档。
CG_READER_UNCONFIGURED没有匹配知识来源的 Reader。KnowledgeRef 的 locator 类型没有已配置读取器。configure_backend注册匹配 Reader，或移除当前不受支持的来源类型。
CG_READER_UNAVAILABLE已配置的 Reader 当前不可用。Reader 抛错、返回不可读结果或后端暂时故障。repair_source检查 Reader 与后端健康状态，恢复后重试读取。
CG_RETRIEVER_UNCONFIGURED当前检索操作没有配置 Retriever。调用能力或知识检索，但未注入相应 Retriever。configure_backend配置对应 Retriever，或改用静态列表与详情查询。
CG_RETRIEVER_UNAVAILABLE已配置的 Retriever 当前不可用。Retriever 抛错或其索引服务无法访问。repair_source恢复 Retriever/索引服务，再重新检索。
CG_SOURCE_UNREADABLE请求的知识或权威来源无法读取。文件不存在、内容不是有效 UTF-8 或来源权限/状态异常。repair_source修复来源路径、编码或可读性后重试。
CG_PATH_TRAVERSAL相对路径越过允许的知识根目录。规范化后的 locator 指向 Provider 根之外。repair_source修复 KnowledgeRef，只使用根目录内的相对路径。
CG_BUDGET_EXCEEDED操作超过响应、条目、分页或文档预算。结果数量、序列化字节或单文档大小超过配置上限。page_or_filter按错误实例的 nextAction 分页、过滤或缩小文档；来源记录超限时修复来源。
CG_TIMEOUT受限操作超过允许时间。通用超时合同；当前 Runtime Adapter 异常与超时会投影为 CG_RUNTIME_UNAVAILABLE。repair_source检查后端任务状态后再重试，避免假定原操作已取消。
CG_PARTIAL_ITEM批量请求中的条目无法完整返回。同一请求包含多类条目失败，无法用单一底层错误代表。fix_input检查逐项结果与 warning，修正失败条目后单独重试。

完整 NextAction 联合类型

NextAction
fix_input
narrow_scope
page_or_filter
configure_backend
repair_source
refresh
select_capabilities
use_retrieval
reduce_document