---
title: "错误"
description: "按错误码定位 Kasumi 参数、权限、平台支持、生命周期和 IO 问题。"
---


> 按错误码定位 Kasumi 参数、权限、平台支持、生命周期和 IO 问题。

## 模块边界

错误码全集来自 `protocol/errors.json`。宿主通过标准错误响应返回错误码；前端总线把
响应转换成普通 `Error`，并把错误码写入 `error.name`。

## 错误形状

```ts
interface KSMError {
  code: KSMErrorCode;
  message: string;
  detail?: unknown;
}
```

Promise 拒绝时不会返回上述对象，而是普通 `Error`：

```ts
try {
  await KSM.fs.readText({ path: 'app://data/config.json' });
} catch (error) {
  if (error instanceof Error) {
    console.info(error.name, error.message);
  }
}
```

如果响应带 `detail`，前端会把它附加到 `Error` 对象上。

## 错误码

| `error.name` |含义 |优先检查 |
| --- | --- | --- |
| `INVALID_ARGS` |参数不符合命令契约 |参数名、类型、未知字段、权限名、事件名 |
| `UNKNOWN_COMMAND` |命令未注册 |协议版本和 `capabilities.commands` |
| `PERMISSION_DENIED` |权限或路径边界拒绝 |权限请求、只读根、picked 句柄 |
| `NOT_SUPPORTED` |当前平台或宿主不支持 |能力列表、平台服务配置 |
| `NOT_FOUND` |资源不存在 |路径、文件是否已删除 |
| `IO_ERROR` |IO 或大小限制失败 |16 MiB 限制、文件权限、临时文件写入 |
| `CANCELLED` |宿主主动取消请求 |路由中断或宿主取消响应 |
| `TIMEOUT` |请求超时 |10 秒默认超时、宿主线程或协程阻塞 |
| `BUSY` |并发或资源忙 |并发上限、重复打开对话框 |
| `INTERNAL_ERROR` |宿主未预期异常 |宿主日志和命令实现 |

## 不是错误码的情况

以下路径只抛普通错误或返回空结果，不应按 Kasumi 错误码处理：

|场景 |表现 |
| --- | --- |
|前端路径守卫拒绝 | `TypeError` |
|标题、正文或文本类型错误 |文案不固定的 `TypeError` |
|桥接未初始化 | `Error`，文案为 `KSM must be initialized before use.` |
|桥接销毁时有未完成请求 |普通 `Error` |
|剪贴板读取失败 | `{ text: '' }` |
|文件不存在时调用 `exists` | `{ exists: false }` |
|文件删除失败或不存在 | `{ removed: false }` |
|对话框取消 | `{ confirmed: false }`或 `{ file: null }` |

## 处理建议

```ts
async function readConfig(): Promise<string | null> {
  try {
    return await KSM.fs.readText({
      path: 'app://data/config.json'
    }) as string;
  } catch (error) {
    if (!(error instanceof Error)) {
      throw error;
    }

    if (error.name === 'NOT_FOUND') {
      return null;
    }

    throw error;
  }
}
```

只对已确认幂等的读取操作考虑重试。写入、删除、退出等非幂等操作不得自动重试。

## Android 等待边界

Android 对话框和运行时权限的宿主内部等待上限是 60 秒，但前端请求默认 10 秒超时。
因此长于 10 秒的用户操作通常先得到 `TIMEOUT`，不会等到底层返回 `false`。

## 排查路径

1. 先区分 `TypeError`、普通 `Error` 和带错误码的桥接错误。
2. 确认桥接已经初始化，且请求期间没有销毁或重建。
3. 核对 `capabilities.commands` 与 `capabilities.permissions`。
4. 路径错误优先检查虚拟根、`..`、`~`、反斜杠和只读根。
5. 大文本错误优先检查 64 KiB 内联阈值和 16 MiB 文件上限。
6. `TIMEOUT` 检查宿主执行线程是否被系统对话框或阻塞 IO 占住。
7. `BUSY` 检查并发命令数和是否有未完成的文件选择器。

## 相关

- [core](/docs/kasumi/api/core)
- [fs](/docs/kasumi/api/fs)
- [types](/docs/kasumi/api/types)