Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): sidebar shape error when documents refresh superseded (#1834)

Andrew Mikofalvy24aa9b45c4d7
diff --git a/.changeset/filetree-superseded-refresh-abort.md b/.changeset/filetree-superseded-refresh-abort.md
new file mode 100644
index 000000000..da4c8e69f
--- /dev/null
+++ b/.changeset/filetree-superseded-refresh-abort.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Fix the FILES sidebar showing "Documents response did not match expected shape." when a documents refresh is superseded during a long initial load of a large project. A refresh aborted mid-response now propagates as a cancellation instead of being mistaken for a malformed server payload, so the sidebar keeps its loading state (or the previous tree) until a completed refresh arrives.
diff --git a/packages/app/src/components/FileTree.superseded-refresh.dom.test.tsx b/packages/app/src/components/FileTree.superseded-refresh.dom.test.tsx
new file mode 100644
index 000000000..c8437e842
--- /dev/null
+++ b/packages/app/src/components/FileTree.superseded-refresh.dom.test.tsx
@@ -0,0 +1,319 @@
+import { afterEach, beforeEach, describe, expect, mock, spyOn, test } from 'bun:test';
+import { cleanup, render, screen, waitFor } from '@testing-library/react';
+import type { ReactNode } from 'react';
+
+function PassThrough({ children }: { children?: ReactNode }) {
+ return <>{children}</>;
+}
+
+let mergedConfig: unknown = null;
+const documentsFetchPlan: Array<
+ (signal: AbortSignal | null | undefined) => Response | Promise<Response>
+> = [];
+let documentsCallCount = 0;
+let resolveTrailingDocuments: ((body: unknown) => void) | null = null;
+
+function jsonResponse(body: unknown, status = 200): Response {
+ return new Response(JSON.stringify(body), {
+ status,
+ headers: { 'content-type': 'application/json' },
+ });
+}
+
+function abortableBodyResponse(signal: AbortSignal | null | undefined): Response {
+ const stream = new ReadableStream({
+ start(controller) {
+ const failWithAbort = () =>
+ controller.error(new DOMException('The operation was aborted.', 'AbortError'));
+ if (!signal) return;
+ if (signal.aborted) failWithAbort();
+ else signal.addEventListener('abort', failWithAbort, { once: true });
+ },
+ });
+ return new Response(stream, {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ });
+}
+
+function deferredDocumentsResponse(): Promise<Response> {
+ return new Promise((resolve) => {
+ resolveTrailingDocuments = (body: unknown) => resolve(jsonResponse(body));
+ });
+}
+
+function docEntry(docName: string) {
+ return {
+ kind: 'document',
+ docName,
+ docExt: '.md',
+ size: 1,
+ modified: '2026-05-18T00:00:00.000Z',
+ };
+}
+
+function makeFetchMock() {
+ return mock(async (input: RequestInfo | URL, init?: RequestInit) => {
+ const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+ if (url.startsWith('/api/documents')) {
+ documentsCallCount += 1;
+ const next = documentsFetchPlan.shift();
+ if (next) return next(init?.signal);
+ return jsonResponse({ documents: [docEntry('notes/fallback')] });
+ }
+ if (url === '/api/workspace') {
+ return jsonResponse({ contentDir: '/tmp/ok', pathSeparator: '/', symlinkResolved: true });
+ }
+ return jsonResponse({ ok: true });
+ });
+}
+
+class StubItem {
+ expanded = false;
+ selected = false;
+ constructor(
+ readonly path: string,
+ private readonly directory: boolean,
+ ) {}
+ getPath() {
+ return this.path;
+ }
+ isDirectory() {
+ return this.directory;
+ }
+ isExpanded() {
+ return this.expanded;
+ }
+ expand() {
+ this.expanded = true;
+ }
+ collapse() {
+ this.expanded = false;
+ }
+ isSelected() {
+ return this.selected;
+ }
+ select() {
+ this.selected = true;
+ }
+ deselect() {
+ this.selected = false;
+ }
+ focus() {}
+}
+
+class StubModel {
+ focusedPath: string | null = null;
+ selectedPaths: string[] = [];
+ items = new Map<string, StubItem>();
+ startRenaming = mock(() => {});
+ getFocusedPath() {
+ return this.focusedPath;
+ }
+ getFocusedIndex() {
+ return -1;
+ }
+ getItemHeight() {
+ return 24;
+ }
+ getSelectedPaths() {
+ return this.selectedPaths;
+ }
+ getItem(path: string) {
+ return this.items.get(path) ?? null;
+ }
+ resetPaths(paths: string[]) {
+ this.items.clear();
+ for (const path of paths) this.items.set(path, new StubItem(path, path.endsWith('/')));
+ }
+ subscribe() {
+ return () => {};
+ }
+ onMutation() {
+ return () => {};
+ }
+ isSearchOpen() {
+ return false;
+ }
+ add(path: string) {
+ this.items.set(path, new StubItem(path, path.endsWith('/')));
+ }
+ move() {}
+ remove() {}
+}
+
+let model = new StubModel();
+
+mock.module('sonner', () => ({ toast: { success: mock(() => {}), error: mock(() => {}) } }));
+mock.module('next-themes', () => ({ useTheme: () => ({ resolvedTheme: 'light' }) }));
+mock.module('@/editor/DocumentContext', () => ({
+ useDocumentContext: () => ({
+ activeDocName: null,
+ activeTarget: null,
+ closeTabs: mock(() => {}),
+ closeDocument: mock(() => {}),
+ closeAndClearDocument: mock(async () => {}),
+ closeAndClearForDelete: mock(async () => {}),
+ closeAndClearForRename: mock(async () => {}),
+ getPoolActiveDocName: () => null,
+ poolHas: () => false,
+ isNewTabActive: false,
+ openTarget: mock(() => {}),
+ prewarm: () => {},
+ remapTabsForRename: mock(() => {}),
+ }),
+}));
+mock.module('@/components/PageListContext', () => ({
+ usePageList: () => ({ addPage: mock(() => {}) }),
+}));
+mock.module('./ui/sidebar', () => ({
+ useSidebar: () => ({ notifySidebarFileSelected: mock(() => {}) }),
+}));
+mock.module('@/lib/config-provider', () => ({
+ useConfigContext: () => ({
+ okignoreBinding: null,
+ projectLocalBinding: null,
+ merged: mergedConfig,
+ }),
+}));
+mock.module('./handoff/useInstalledAgents', () => ({ useInstalledAgents: () => ({ states: {} }) }));
+mock.module('./handoff/useHandoffDispatch', () => ({
+ buildFolderHandoffInput: () => null,
+ buildHandoffInput: () => null,
+ useHandoffDispatch: () => ({ dispatch: mock(async () => ({ ok: true as const })) }),
+}));
+mock.module('./handoff/OpenInAgentContextSubmenu', () => ({
+ OpenInAgentContextSubmenu: () => null,
+}));
+mock.module('./sidebar-hover-prewarm', () => ({
+ cancelHoverPrewarm: () => {},
+ scheduleHoverPrewarm: () => {},
+}));
+mock.module('@/components/ui/button', () => ({
+ Button: ({ children, ...props }: { children?: ReactNode; [k: string]: unknown }) => (
+ <button type="button" {...props}>
+ {children}
+ </button>
+ ),
+}));
+mock.module('@/components/ui/dialog', () => ({ Dialog: PassThrough }));
+mock.module('@/components/ui/dropdown-menu', () => ({
+ DropdownMenu: PassThrough,
+ DropdownMenuCheckboxItem: PassThrough,
+ DropdownMenuContent: PassThrough,
+ DropdownMenuItem: PassThrough,
+ DropdownMenuSeparator: () => <hr />,
+ DropdownMenuSub: PassThrough,
+ DropdownMenuSubContent: PassThrough,
+ DropdownMenuSubTrigger: PassThrough,
+ DropdownMenuTrigger: PassThrough,
+}));
+mock.module('@/components/ui/skeleton', () => ({
+ Skeleton: ({ className }: { className?: string }) => <span className={className} />,
+}));
+mock.module('@/components/DeleteConfirmationDialog', () => ({
+ DeleteConfirmationDialog: () => null,
+}));
+mock.module('@/components/NewItemDialog', () => ({ NewItemDialog: () => null }));
+mock.module('@/components/TrashFailureModal', () => ({
+ TrashFailureModal: () => null,
+ coerceTrashFailureReason: (reason: string) => reason,
+}));
+mock.module('@/components/use-selection-mirror', () => ({
+ asDirectoryHandle: (item: StubItem | null) => (item?.isDirectory() ? item : null),
+ useSelectionMirror: () => {},
+}));
+mock.module('@pierre/trees', () => ({
+ FILE_TREE_TAG_NAME: 'ok-file-tree',
+ themeToTreeStyles: () => ({}),
+}));
+mock.module('@pierre/trees/react', () => ({
+ useFileTree: () => ({ model }),
+ FileTree: ({ header }: { header?: ReactNode }) => (
+ <div data-testid="fake-pierre-tree" role="tree">
+ {header}
+ </div>
+ ),
+}));
+
+const { FileTree } = await import('./FileTree');
+
+describe('FileTree superseded documents refresh', () => {
+ let consoleWarnSpy: ReturnType<typeof spyOn>;
+
+ beforeEach(() => {
+ model = new StubModel();
+ mergedConfig = null;
+ documentsFetchPlan.length = 0;
+ documentsCallCount = 0;
+ resolveTrailingDocuments = null;
+ globalThis.fetch = makeFetchMock() as unknown as typeof fetch;
+ consoleWarnSpy = spyOn(console, 'warn').mockImplementation(() => {});
+ });
+
+ afterEach(() => {
+ cleanup();
+ consoleWarnSpy.mockRestore();
+ });
+
+ test('initial load: superseding the in-flight refresh keeps the skeleton — no terminal shape error', async () => {
+ documentsFetchPlan.push(
+ (signal) => abortableBodyResponse(signal),
+ () => deferredDocumentsResponse(),
+ );
+ render(<FileTree />);
+
+ await waitFor(() => expect(documentsCallCount).toBe(1));
+ expect(screen.getByRole('status', { name: /loading files/i })).toBeTruthy();
+
+ window.dispatchEvent(new Event('focus'));
+
+ await waitFor(() => expect(documentsCallCount).toBe(2));
+
+ expect(screen.queryByText(/did not match expected shape/i)).toBeNull();
+ expect(screen.queryByRole('alert')).toBeNull();
+ expect(screen.queryByText(/no files yet/i)).toBeNull();
+ expect(screen.getByRole('status', { name: /loading files/i })).toBeTruthy();
+
+ resolveTrailingDocuments?.({ documents: [docEntry('notes/a')] });
+ await screen.findByTestId('fake-pierre-tree');
+ expect(screen.queryByText(/did not match expected shape/i)).toBeNull();
+ expect(screen.queryByRole('alert')).toBeNull();
+
+ const fetchFailedWarns = consoleWarnSpy.mock.calls.filter(
+ (args) => typeof args[0] === 'string' && args[0].includes('[FileTree] fetch failed:'),
+ );
+ expect(fetchFailedWarns).toEqual([]);
+ });
+
+ test('after a successful load: a superseded refresh keeps the previous tree — no alert banner', async () => {
+ documentsFetchPlan.push(
+ () => jsonResponse({ documents: [docEntry('notes/a')] }),
+ (signal) => abortableBodyResponse(signal),
+ () => deferredDocumentsResponse(),
+ );
+ render(<FileTree />);
+ await screen.findByTestId('fake-pierre-tree');
+
+ window.dispatchEvent(new Event('focus'));
+ await waitFor(() => expect(documentsCallCount).toBe(2));
+
+ window.dispatchEvent(new Event('focus'));
+ await waitFor(() => expect(documentsCallCount).toBe(3));
+
+ expect(screen.queryByRole('alert')).toBeNull();
+ expect(screen.queryByText(/did not match expected shape/i)).toBeNull();
+ expect(screen.getByTestId('fake-pierre-tree')).toBeTruthy();
+
+ resolveTrailingDocuments?.({ documents: [docEntry('notes/a'), docEntry('notes/b')] });
+ await waitFor(() => {
+ expect(screen.getByTestId('fake-pierre-tree')).toBeTruthy();
+ expect(screen.queryByRole('alert')).toBeNull();
+ });
+
+ const fetchFailedWarns = consoleWarnSpy.mock.calls.filter(
+ (args) => typeof args[0] === 'string' && args[0].includes('[FileTree] fetch failed:'),
+ );
+ expect(fetchFailedWarns).toEqual([]);
+ });
+});
diff --git a/packages/app/src/lib/parse-server-response.test.ts b/packages/app/src/lib/parse-server-response.test.ts
index d0037ef1a..69da38162 100644
--- a/packages/app/src/lib/parse-server-response.test.ts
+++ b/packages/app/src/lib/parse-server-response.test.ts
@@ -77,6 +77,78 @@ describe('parseServerResponse', () => {
expect(result.body).toBeNull();
}
});
+
+ test('2xx whose body read is aborted mid-stream → cancellation stays observable to the caller', async () => {
+ const stream = new ReadableStream({
+ start(controller) {
+ controller.error(new DOMException('The operation was aborted.', 'AbortError'));
+ },
+ });
+ const res = new Response(stream, {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ });
+
+ let result: Awaited<ReturnType<typeof parseServerResponse>> | undefined;
+ try {
+ result = await parseServerResponse(res, 'unused');
+ } catch (err) {
+ expect(err instanceof Error && err.name === 'AbortError').toBe(true);
+ return;
+ }
+ expect(result).not.toEqual({ ok: true, body: null });
+ });
+
+ test('5xx whose body read is aborted mid-stream → cancellation stays observable, not a server-error title', async () => {
+ const stream = new ReadableStream({
+ start(controller) {
+ controller.error(new DOMException('The operation was aborted.', 'AbortError'));
+ },
+ });
+ const res = new Response(stream, {
+ status: 500,
+ headers: { 'content-type': 'application/json' },
+ });
+
+ let result: Awaited<ReturnType<typeof parseServerResponse>> | undefined;
+ try {
+ result = await parseServerResponse(res, 'unused');
+ } catch (err) {
+ expect(err instanceof Error && err.name === 'AbortError').toBe(true);
+ return;
+ }
+ expect(result).not.toMatchObject({ ok: false });
+ expect(result).not.toEqual({ ok: true, body: null });
+ });
+
+ test('aborted body read emits no transport console.warn (no per-supersede log spam)', async () => {
+ const stream = new ReadableStream({
+ start(controller) {
+ controller.error(new DOMException('The operation was aborted.', 'AbortError'));
+ },
+ });
+ const res = new Response(stream, {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ });
+
+ const consoleWarnSpy: unknown[][] = [];
+ const originalWarn = console.warn;
+ console.warn = (...args: unknown[]) => {
+ consoleWarnSpy.push(args);
+ };
+ try {
+ await parseServerResponse(res, 'unused').catch((err: unknown) => {
+ if (!(err instanceof Error && err.name === 'AbortError')) throw err;
+ });
+ const transportWarns = consoleWarnSpy.filter(
+ (args) => typeof args[0] === 'string' && args[0].includes('[parse-server-response]'),
+ );
+ expect(transportWarns).toEqual([]);
+ } finally {
+ console.warn = originalWarn;
+ }
+ });
});
describe('parseSuccessOrWarn', () => {
diff --git a/packages/app/src/lib/parse-server-response.ts b/packages/app/src/lib/parse-server-response.ts
index 4b6318eb5..9af7ac1cd 100644
--- a/packages/app/src/lib/parse-server-response.ts
+++ b/packages/app/src/lib/parse-server-response.ts
@@ -12,6 +12,9 @@ export async function parseServerResponse(
} catch (err) {
parseErr = err;
}
+ if (parseErr instanceof Error && parseErr.name === 'AbortError') {
+ throw parseErr;
+ }
if (res.ok) {
if (parseErr !== undefined) {
console.warn(