# 错误码

> 每个文档引擎错误码，比如 SAVE_CONFLICT、MISSING_ASSETS 和 UNSAVED_CHANGES，以及触发时机和处理方法。

Source: https://fabricjs-document-engine.jscrate.dev/zh/docs/api/error-codes
Last updated: 2026-09-28

每种失败都是带稳定 `code` 的 `DocumentEngineError`。文档引擎错误码在 1.x 期间永远不会变，所以请按 code 判断，不要按消息文字判断。

```ts
import { isDocumentEngineError } from "fabricjs-document-engine";

try {
  await engine.load(id);
} catch (error) {
  if (isDocumentEngineError(error) && error.code === "UNSAVED_CHANGES") {
    await engine.save();
    await engine.load(id);
  }
}
```

除了 `code`，错误还可能带有 `issues`、`unknownTypes`、`missingAssets`、`missingFonts`、`problems`、`migrationFrom`、`retryable` 和 `cause`。

## 全部文档引擎错误码

| 错误码                   | 触发时机                                      |
| ------------------------ | --------------------------------------------- |
| `INVALID_DOCUMENT`       | 文档结构不对，或导入的文本不是 JSON           |
| `UNSAFE_DOCUMENT`        | 不安全的图片地址、对象太多或嵌套太深          |
| `UNSUPPORTED_SCHEMA`     | 由这个包更新的大版本写入                      |
| `UNKNOWN_OBJECT_TYPE`    | 自定义类没有注册                              |
| `INVALID_CUSTOM_OBJECT`  | 注册的类没有静态 `type`，或不是 Fabric.js 类  |
| `MIGRATION_FAILED`       | 旧文档无法升级                                |
| `LOAD_ABORTED`           | 更新的加载或 `destroy` 中止了这次加载         |
| `LOAD_FAILED`            | Fabric.js 或存储加载失败                      |
| `MISSING_ASSETS`         | 有图片无法加载                                |
| `MISSING_FONTS`          | 字体不可用，且开启了 `requireFonts`           |
| `ASSET_UPLOAD_FAILED`    | `upload` 处理函数失败                         |
| `UNSAVED_CHANGES`        | 打开另一份文档会丢掉未保存的改动              |
| `STORAGE_MISSING`        | 没有存储却调用了 `load`、`save` 或自动保存    |
| `SAVE_FAILED`            | 重试后存储仍然拒绝                            |
| `SAVE_CONFLICT`          | 另一个标签页或设备先保存了                    |
| `SAVE_CANCELLED`         | 因为打开了另一份文档或引擎被销毁，保存被丢弃  |
| `DOCUMENT_NOT_FOUND`     | 内置适配器里没有这份文档                      |
| `HISTORY_FAILED`         | 撤销或重做无法重建对象                        |
| `RECOVERY_MISSING`       | 没有配置恢复                                  |
| `RECOVERY_NOT_FOUND`     | 没有恢复副本                                  |
| `RECOVERY_FAILED`        | 无法写入恢复副本                              |
| `VERSIONS_UNSUPPORTED`   | 存储没有版本相关的方法                        |
| `VERSION_NOT_FOUND`      | 没有这个版本                                  |
| `VERSION_FAILED`         | 自动版本失败                                  |
| `INVALID_EXPORT_OPTIONS` | 导出配置无效                                  |
| `EXPORT_BLOCKED`         | 有图片或字体会让导出出错，见 `error.problems` |
| `EXPORT_ABORTED`         | 导出被取消                                    |
| `EXPORT_FAILED`          | 渲染失败                                      |
| `ENGINE_DESTROYED`       | 在 `destroy()` 之后仍使用了引擎               |

## 需要界面处理的几个

大多数文档引擎错误码记下日志就可以了。下面这几个需要用户做决定，请给它们一个对话框：`SAVE_CONFLICT`（[保存冲突](https://fabricjs-document-engine.jscrate.dev/zh/docs/guides/save-conflicts)）、`MISSING_ASSETS`（[图片和字体](https://fabricjs-document-engine.jscrate.dev/zh/docs/guides/assets-and-fonts)）和 `UNSAVED_CHANGES`。完整的处理代码见[上线清单](https://fabricjs-document-engine.jscrate.dev/zh/docs/production/production-checklist)。