资源注册失败
在数据与本体 → 资源接入查看表单错误和 Resource 详情。确认资源 ID 唯一、资源类型在目录中、连接引用来自已保存的 Secret，能力配置符合所选 adapter schema。若页面没有目标资源类型，先检查服务版本和 adapter registry；不要手写一个未注册的resourceType。
同步作业失败
在资源详情的同步作业查看状态、阶段、进度和failedReason；在错误页查看 dead-letter payload。修正 Secret、网络、认证或能力范围后再重试。首次接入优先 full sync；SAP OData 先缩小服务选择，数据库先缩小 allowlist 和表列上限。
Snapshot 缺失或投影失败
本体空间中的missing_snapshot 表示尚无当前快照，publish_failed 表示发布阶段失败，projection_failed 表示快照存在但运行时投影失败。回到资源详情确认最近一次 sync 已完成并记录 snapshot ID；必要时执行 full sync。修复前不要让 Agent 消费该资源。
实体搜索为空
在本体空间先按资源和实体类型缩小范围，再检查关键词、外部键和别名。确认图谱健康状态为ready，目标服务在同步时已选择，数据库 capabilities 没有过滤目标表。宽泛查询达到上限时缩小关键词，不要把截断结果当成完整导出。
Action 不可用
查看discoverActions 的 deniedActions.reasonCode 和 stage：
discovery_mode_manual_only：动作不能自动规划；target_entity_type_not_supported：目标实体类型不匹配；analysis_contract_missing或query_endpoint_missing：语义模型契约或查询端点未准备好；policy_binding:deny：策略拒绝；policy_binding:require_approval/approval_required：需要审批。
模拟或执行失败
先用同一 target 和 params 重跑simulateAction。检查实体是否唯一、input schema、连接解析、策略结果、审批 fingerprint、approvalRequestId 和 expectedEffect。只读动作模拟成功后再执行；高风险动作进入治理 → 审批。
ChatKit 或审计异常
确认 ChatKit 已配置为当前组织和工作空间使用的地址，请求携带当前 tenant、organization、user、workspace 和 Assistant 上下文。若 ChatKit 能打开但工具调用失败，查看 Data Xpert API 响应和执行审计中的policyDecision、snapshotId、traceId，并确认没有使用另一个组织的 token。