Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

fix: improve EdgeEver ZIP import diagnostics

yomac00773b01626
diff --git a/apps/web/src/components/settings/DataExportCard.tsx b/apps/web/src/components/settings/DataExportCard.tsx
index c08b79d9..315e4c3c 100644
--- a/apps/web/src/components/settings/DataExportCard.tsx
+++ b/apps/web/src/components/settings/DataExportCard.tsx
@@ -12,10 +12,11 @@ import {
DialogHeader,
DialogTitle,
} from "@/components/ui/dialog";
-import { api } from "@/lib/api";
+import { api, ApiRequestError } from "@/lib/api";
import {
createEdgeEverZip,
downloadEdgeEverZip,
+ EdgeEverZipImportError,
parseEdgeEverZip,
restoreEdgeEverZip,
type EdgeEverZipProgress,
@@ -42,13 +43,38 @@ export const DataExportCard = () => {
const [operation, setOperation] = useState<OperationKind>("export");
const [progress, setProgress] = useState<EdgeEverZipProgress>({ completed: 0, total: 0 });
const [pendingImport, setPendingImport] = useState<ParsedEdgeEverZip | null>(null);
+ const [errorMessage, setErrorMessage] = useState<string | null>(null);
const busy = state === "working";
+ const describeImportError = (error: unknown) => {
+ if (error instanceof EdgeEverZipImportError) {
+ switch (error.code) {
+ case "invalidZip": return t("dataExport.importErrors.invalidZip");
+ case "missingManifest": return t("dataExport.importErrors.missingManifest");
+ case "unsupportedFormat": return t("dataExport.importErrors.unsupportedFormat");
+ case "unsupportedVersion": return t("dataExport.importErrors.unsupportedVersion");
+ case "invalidManifest": return t("dataExport.importErrors.invalidManifest");
+ case "missingData": return t("dataExport.importErrors.missingData");
+ case "invalidData": return t("dataExport.importErrors.invalidData");
+ case "incompleteData": return t("dataExport.importErrors.incompleteData");
+ case "incompleteResources": return t("dataExport.importErrors.incompleteResources");
+ }
+ }
+ if (error instanceof ApiRequestError) {
+ return t("dataExport.importErrors.serverRejected", { message: error.message });
+ }
+ if (error instanceof TypeError) {
+ return t("dataExport.importErrors.network");
+ }
+ return t("dataExport.importErrors.unknown");
+ };
+
const handleExport = async () => {
setOperation("export");
setState("working");
setProgress({ completed: 0, total: 0 });
+ setErrorMessage(null);
try {
const blob = await createEdgeEverZip(
{ listNotebooks: api.listNotebooks, getPage: api.getJsonBackupPage, getResourceBlob: api.getResourceBlob },
@@ -59,6 +85,7 @@ export const DataExportCard = () => {
setState("complete");
} catch (error) {
console.error("Failed to export EdgeEver ZIP", error);
+ setErrorMessage(t("dataExport.error"));
setState("error");
}
};
@@ -68,12 +95,14 @@ export const DataExportCard = () => {
setOperation("import");
setState("working");
setProgress({ completed: 0, total: 0 });
+ setErrorMessage(null);
try {
const parsed = await parseEdgeEverZip(file);
setPendingImport(parsed);
setState("idle");
} catch (error) {
console.error("Invalid EdgeEver ZIP", error);
+ setErrorMessage(describeImportError(error));
setState("error");
} finally {
if (fileInputRef.current) fileInputRef.current.value = "";
@@ -87,6 +116,7 @@ export const DataExportCard = () => {
setOperation("import");
setState("working");
setProgress({ completed: 0, total: 0 });
+ setErrorMessage(null);
try {
await restoreEdgeEverZip(
archive,
@@ -101,6 +131,7 @@ export const DataExportCard = () => {
setState("complete");
} catch (error) {
console.error("Failed to import EdgeEver ZIP", error);
+ setErrorMessage(describeImportError(error));
setState("error");
}
};
@@ -142,7 +173,7 @@ export const DataExportCard = () => {
</div>
) : null}
{state === "complete" ? <p className="flex items-center gap-1.5 text-xs text-emerald-700"><CheckCircle2 className="h-3.5 w-3.5" />{operation === "import" ? t("dataExport.importComplete") : t("dataExport.complete")}</p> : null}
- {state === "error" ? <p className="flex items-center gap-1.5 text-xs text-red-600" role="alert"><AlertCircle className="h-3.5 w-3.5" />{operation === "import" ? t("dataExport.importError") : t("dataExport.error")}</p> : null}
+ {state === "error" ? <p className="flex items-center gap-1.5 text-xs text-red-600" role="alert"><AlertCircle className="h-3.5 w-3.5 shrink-0" />{errorMessage}</p> : null}
</CardContent>
</Card>
diff --git a/apps/web/src/i18n/resources/en-US.ts b/apps/web/src/i18n/resources/en-US.ts
index 34a87d8a..529a69e6 100644
--- a/apps/web/src/i18n/resources/en-US.ts
+++ b/apps/web/src/i18n/resources/en-US.ts
@@ -174,7 +174,20 @@ export const enUS = {
complete: "Export complete. Your ZIP download has started.",
error: "Export failed. Check your connection and try again.",
importComplete: "EdgeEver ZIP imported successfully.",
- importError: "The file is invalid or could not be imported. Make sure it is an EdgeEver ZIP and check your connection.",
+ importErrors: {
+ invalidZip: "This file cannot be extracted. It is not a valid ZIP or is damaged.",
+ missingManifest: "This file cannot be identified because manifest.json is missing.",
+ unsupportedFormat: "This archive format is not supported. Select a ZIP exported by EdgeEver.",
+ unsupportedVersion: "This EdgeEver ZIP requires a newer version of EdgeEver. Upgrade before importing it.",
+ invalidManifest: "manifest.json is invalid, so the archive version and integrity cannot be verified.",
+ missingData: "The archive is missing structured notebook or note data.",
+ invalidData: "The archive contains invalid structured data and may have been modified or damaged.",
+ incompleteData: "Notes or revision history are incomplete and do not match the manifest.",
+ incompleteResources: "Images or attachments are missing or damaged and do not match the manifest.",
+ serverRejected: "The server could not write the imported data: {{message}}",
+ network: "EdgeEver could not be reached during import. Check your connection and try again.",
+ unknown: "Import failed because of an unknown error. Export a new archive and try again.",
+ },
importConfirmTitle: "Import EdgeEver ZIP",
importConfirmDescription: "This file contains {{memos}} notes and {{resources}} resources. Other data in this instance is preserved, but matching EdgeEver IDs are overwritten.",
confirmImport: "Import",
diff --git a/apps/web/src/i18n/resources/zh-CN.ts b/apps/web/src/i18n/resources/zh-CN.ts
index 4ad73c66..fa1ae025 100644
--- a/apps/web/src/i18n/resources/zh-CN.ts
+++ b/apps/web/src/i18n/resources/zh-CN.ts
@@ -174,7 +174,20 @@ export const zhCN = {
complete: "导出完成,ZIP 文件已开始下载。",
error: "导出失败,请检查网络连接后重试。",
importComplete: "EdgeEver ZIP 导入完成。",
- importError: "文件无效或导入失败,请确认它是 EdgeEver ZIP 并检查网络连接。",
+ importErrors: {
+ invalidZip: "无法解压这个文件:它不是有效的 ZIP,或文件已经损坏。",
+ missingManifest: "无法识别这个文件:压缩包中缺少 manifest.json。",
+ unsupportedFormat: "不支持这个压缩包格式:请选择由 EdgeEver 导出的 ZIP。",
+ unsupportedVersion: "当前版本无法导入这个 EdgeEver ZIP,请先升级 EdgeEver。",
+ invalidManifest: "manifest.json 内容无效,无法确认压缩包的版本和完整性。",
+ missingData: "压缩包缺少笔记本或笔记的结构化数据文件。",
+ invalidData: "压缩包中的结构化数据格式无效,可能已被修改或损坏。",
+ incompleteData: "压缩包中的笔记或历史版本不完整,与清单记录不一致。",
+ incompleteResources: "压缩包中的图片或附件缺失、损坏,与清单记录不一致。",
+ serverRejected: "服务器未能写入导入数据:{{message}}",
+ network: "导入时无法连接 EdgeEver 服务,请检查网络连接后重试。",
+ unknown: "导入失败,发生了无法识别的错误。请重新导出后再试。",
+ },
importConfirmTitle: "导入 EdgeEver ZIP",
importConfirmDescription: "文件包含 {{memos}} 篇笔记和 {{resources}} 个资源。导入会保留当前实例中的其他数据,但会覆盖相同 EdgeEver ID 的内容。",
confirmImport: "确认导入",
diff --git a/apps/web/src/lib/json-backup.ts b/apps/web/src/lib/json-backup.ts
index e84a73ef..5fe5406a 100644
--- a/apps/web/src/lib/json-backup.ts
+++ b/apps/web/src/lib/json-backup.ts
@@ -28,6 +28,27 @@ export type EdgeEverZipProgress = {
total: number;
};
+export type EdgeEverZipImportErrorCode =
+ | "invalidZip"
+ | "missingManifest"
+ | "unsupportedFormat"
+ | "unsupportedVersion"
+ | "invalidManifest"
+ | "missingData"
+ | "invalidData"
+ | "incompleteData"
+ | "incompleteResources";
+
+export class EdgeEverZipImportError extends Error {
+ code: EdgeEverZipImportErrorCode;
+
+ constructor(code: EdgeEverZipImportErrorCode, cause?: unknown) {
+ super(code, { cause });
+ this.name = "EdgeEverZipImportError";
+ this.code = code;
+ }
+}
+
type JsonBackupPage = {
memos: MemoDetail[];
resources: Resource[];
@@ -212,18 +233,26 @@ export const createEdgeEverZip = async (
});
};
-const parseJsonFile = (files: Record<string, Uint8Array>, path: string) => {
+const parseJsonFile = (
+ files: Record<string, Uint8Array>,
+ path: string,
+ missingCode: EdgeEverZipImportErrorCode = "missingData"
+) => {
const data = files[path];
if (!data) {
- throw new Error(`Backup file is missing: ${path}`);
+ throw new EdgeEverZipImportError(missingCode);
+ }
+ try {
+ return JSON.parse(strFromU8(data)) as unknown;
+ } catch (error) {
+ throw new EdgeEverZipImportError(path === "manifest.json" ? "invalidManifest" : "invalidData", error);
}
- return JSON.parse(strFromU8(data)) as unknown;
};
const unzipBlob = async (blob: Blob) => {
const bytes = new Uint8Array(await blob.arrayBuffer());
return new Promise<Record<string, Uint8Array>>((resolve, reject) => {
- unzip(bytes, (error, files) => error ? reject(error) : resolve(files));
+ unzip(bytes, (error, files) => error ? reject(new EdgeEverZipImportError("invalidZip", error)) : resolve(files));
});
};
@@ -241,14 +270,40 @@ const sortNotebooksForRestore = (notebooks: JsonBackupNotebook[]) => {
export const parseEdgeEverZip = async (blob: Blob): Promise<ParsedEdgeEverZip> => {
const files = await unzipBlob(blob);
- const manifest = JsonBackupManifestSchema.parse(parseJsonFile(files, "manifest.json"));
+ const manifestValue = parseJsonFile(files, "manifest.json", "missingManifest");
+ if (!manifestValue || typeof manifestValue !== "object") {
+ throw new EdgeEverZipImportError("invalidManifest");
+ }
+ const manifestRecord = manifestValue as Record<string, unknown>;
+ if (manifestRecord.format !== EDGEEVER_ZIP_FORMAT) {
+ throw new EdgeEverZipImportError("unsupportedFormat");
+ }
+ if (manifestRecord.formatVersion !== EDGEEVER_ZIP_FORMAT_VERSION) {
+ throw new EdgeEverZipImportError("unsupportedVersion");
+ }
+ const manifestResult = JsonBackupManifestSchema.safeParse(manifestValue);
+ if (!manifestResult.success) {
+ throw new EdgeEverZipImportError("invalidManifest", manifestResult.error);
+ }
+ const manifest = manifestResult.data;
const notebooksValue = parseJsonFile(files, "notebooks.json");
if (!Array.isArray(notebooksValue)) {
- throw new Error("notebooks.json must contain an array.");
+ throw new EdgeEverZipImportError("invalidData");
}
- const notebooks = sortNotebooksForRestore(notebooksValue.map((item) => JsonBackupNotebookSchema.parse(item)));
+ const notebooksResult = JsonBackupNotebookSchema.array().safeParse(notebooksValue);
+ if (!notebooksResult.success) {
+ throw new EdgeEverZipImportError("invalidData", notebooksResult.error);
+ }
+ const notebooks = sortNotebooksForRestore(notebooksResult.data);
const memoPaths = Object.keys(files).filter((path) => /^memos\/[^/]+\.json$/.test(path)).sort();
- const memos = memoPaths.map((path) => JsonBackupMemoSchema.parse(parseJsonFile(files, path)) as JsonBackupMemo);
+ const memos: JsonBackupMemo[] = [];
+ for (const path of memoPaths) {
+ const memoResult = JsonBackupMemoSchema.safeParse(parseJsonFile(files, path));
+ if (!memoResult.success) {
+ throw new EdgeEverZipImportError("invalidData", memoResult.error);
+ }
+ memos.push(memoResult.data as JsonBackupMemo);
+ }
const markdownCount = Object.keys(files).filter((path) => /^notes\/.+\.md$/.test(path)).length;
if (
@@ -256,19 +311,19 @@ export const parseEdgeEverZip = async (blob: Blob): Promise<ParsedEdgeEverZip> =
|| manifest.counts.memos !== memos.length
|| manifest.counts.memos !== markdownCount
) {
- throw new Error("Backup manifest counts do not match the archive contents.");
+ throw new EdgeEverZipImportError("incompleteData");
}
const resources = memos.flatMap((memo) => memo.resources);
const revisionCount = memos.reduce((count, memo) => count + memo.revisions.length, 0);
if (manifest.counts.revisions !== revisionCount) {
- throw new Error("Backup revisions are incomplete.");
+ throw new EdgeEverZipImportError("incompleteData");
}
if (
manifest.counts.resources !== resources.length
|| resources.some((resource) => !files[resource.archivePath] || files[resource.archivePath].byteLength !== resource.byteSize)
) {
- throw new Error("Backup resources are incomplete.");
+ throw new EdgeEverZipImportError("incompleteResources");
}
return { manifest, notebooks, memos, files };
diff --git a/tests/json-backup.test.ts b/tests/json-backup.test.ts
index b7b4601f..a7f7963d 100644
--- a/tests/json-backup.test.ts
+++ b/tests/json-backup.test.ts
@@ -1,7 +1,11 @@
import { describe, expect, test } from "bun:test";
import type { JsonBackupMemo, JsonBackupNotebook, MemoDetail, Notebook, Resource } from "@edgeever/shared";
-import { strFromU8 } from "fflate";
-import { createEdgeEverZip, parseEdgeEverZip, restoreEdgeEverZip } from "../apps/web/src/lib/json-backup";
+import { strFromU8, strToU8, zipSync } from "fflate";
+import {
+ createEdgeEverZip,
+ parseEdgeEverZip,
+ restoreEdgeEverZip,
+} from "../apps/web/src/lib/json-backup";
const notebook = (id: string, name: string, parentId: string | null = null): Notebook => ({
id,
@@ -56,6 +60,34 @@ const resource: Resource = {
};
describe("EdgeEver ZIP", () => {
+ test("reports actionable archive validation errors", async () => {
+ await expect(parseEdgeEverZip(new Blob(["not a zip"]))).rejects.toEqual(
+ expect.objectContaining({ code: "invalidZip" })
+ );
+
+ await expect(parseEdgeEverZip(new Blob([zipSync({ "notebooks.json": strToU8("[]") })]))).rejects.toEqual(
+ expect.objectContaining({ code: "missingManifest" })
+ );
+
+ const manifest = {
+ format: "another-app",
+ formatVersion: 1,
+ schemaVersion: 1,
+ edgeeverVersion: "0.1.13",
+ buildId: "test-build",
+ exportedAt: "2026-07-14T00:00:00.000Z",
+ includesTrash: false,
+ counts: { notebooks: 0, memos: 0, revisions: 0, resources: 0 },
+ };
+ await expect(parseEdgeEverZip(new Blob([zipSync({
+ "manifest.json": strToU8(JSON.stringify(manifest)),
+ })]))).rejects.toEqual(expect.objectContaining({ code: "unsupportedFormat" }));
+
+ await expect(parseEdgeEverZip(new Blob([zipSync({
+ "manifest.json": strToU8(JSON.stringify({ ...manifest, format: "edgeever-zip", formatVersion: 99 })),
+ })]))).rejects.toEqual(expect.objectContaining({ code: "unsupportedVersion" }));
+ });
+
test("combines readable Markdown with versioned recovery data", async () => {
const blob = await createEdgeEverZip(
{