Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

fix: live chunk-settings validation and stop clobbering unsaved edits (#2430)

Nathan Bakareb632faf8e811
diff --git a/frontend/app/settings/_components/ingest-settings-section.test.tsx b/frontend/app/settings/_components/ingest-settings-section.test.tsx
new file mode 100644
index 000000000..7bf10d04d
--- /dev/null
+++ b/frontend/app/settings/_components/ingest-settings-section.test.tsx
@@ -0,0 +1,376 @@
+import type { RequestHandler } from "msw";
+import { HttpResponse, http } from "msw";
+import { describe, expect, it, vi } from "vitest";
+import { IngestSettingsSection } from "@/app/settings/_components/ingest-settings-section";
+import { authPresets } from "@/test-utils/fixtures/auth";
+import { makeSettings } from "@/test-utils/fixtures/settings";
+import { server } from "@/test-utils/msw/server";
+import {
+ act,
+ fireEvent,
+ renderWithProviders,
+ screen,
+ waitFor,
+} from "@/test-utils/render";
+
+// ── Global mocks ─────────────────────────────────────────────────────────────
+
+vi.mock("@/lib/analytics", () => ({ trackButton: vi.fn() }));
+
+// Avoid BrandProvider needing its own auth bootstrap; the component only reads
+// isCloudBrand to conditionally show one UI branch.
+vi.mock("@/contexts/brand-context", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("@/contexts/brand-context")>()),
+ useIsCloudBrand: () => false,
+}));
+
+// Suppress toasts — we're not asserting on them here and they can leak into
+// unrelated assertions through aria-live regions.
+vi.mock("sonner", () => ({ toast: { success: vi.fn(), error: vi.fn() } }));
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Default GET handlers for every test.
+ * - /api/settings → 1024 / 50 chunk settings, VLM disabled so the auto-select
+ * effect never fires an extra /api/models/catalog request.
+ * - /api/models/catalog → empty provider list; prevents unhandled-request error
+ * from useGetModelCatalogQuery (always enabled for authed users).
+ */
+function baseHandlers(
+ knowledge: { chunk_size: number; chunk_overlap: number } = {
+ chunk_size: 1024,
+ chunk_overlap: 50,
+ },
+): RequestHandler[] {
+ return [
+ http.get("/api/settings", () =>
+ HttpResponse.json(
+ makeSettings({
+ knowledge,
+ show_vlm_settings: false,
+ }),
+ ),
+ ),
+ http.get("/api/models/catalog", () => HttpResponse.json({ providers: [] })),
+ ];
+}
+
+function renderSection(
+ extraHandlers: RequestHandler[] = [],
+ knowledge?: { chunk_size: number; chunk_overlap: number },
+) {
+ return renderWithProviders(<IngestSettingsSection />, {
+ providers: ["tooltip", "auth", "unsavedChanges"],
+ auth: authPresets.admin,
+ handlers: [...baseHandlers(knowledge), ...extraHandlers],
+ });
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe("IngestSettingsSection", () => {
+ // ── Baseline ──────────────────────────────────────────────────────────────
+
+ describe("initial load", () => {
+ it("populates chunk size and overlap from server", async () => {
+ // Use server values that differ from the component defaults (1024 / 50)
+ // so this test fails if server→form synchronization stops working.
+ renderSection([], { chunk_size: 768, chunk_overlap: 128 });
+
+ expect(
+ await screen.findByRole("spinbutton", { name: /chunk size/i }),
+ ).toHaveValue(768);
+ expect(
+ screen.getByRole("spinbutton", { name: /chunk overlap/i }),
+ ).toHaveValue(128);
+ });
+ });
+
+ // ── Group 1: Validation error display ─────────────────────────────────────
+
+ describe("validation error display", () => {
+ it("shows no error on load with valid settings", async () => {
+ renderSection();
+
+ // Wait for the form to fully render after auth + settings load.
+ await screen.findByRole("spinbutton", { name: /chunk size/i });
+ expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+ });
+
+ it("shows 'Chunk size must be at least 1' when chunk size is set to 0", async () => {
+ renderSection();
+
+ const input = await screen.findByRole("spinbutton", {
+ name: /chunk size/i,
+ });
+ fireEvent.change(input, { target: { value: "0" } });
+
+ expect(await screen.findByRole("alert")).toHaveTextContent(
+ "Chunk size must be at least 1",
+ );
+ });
+
+ it("shows 'Chunk overlap must be less than chunk size' when overlap equals chunk size", async () => {
+ renderSection();
+
+ await screen.findByRole("spinbutton", { name: /chunk size/i });
+ const overlapInput = screen.getByRole("spinbutton", {
+ name: /chunk overlap/i,
+ });
+ fireEvent.change(overlapInput, { target: { value: "1024" } });
+
+ expect(await screen.findByRole("alert")).toHaveTextContent(
+ "Chunk overlap must be less than chunk size",
+ );
+ });
+
+ it("clears the error when the user corrects invalid values", async () => {
+ renderSection();
+
+ const input = await screen.findByRole("spinbutton", {
+ name: /chunk size/i,
+ });
+
+ // Introduce error.
+ fireEvent.change(input, { target: { value: "0" } });
+ expect(await screen.findByRole("alert")).toBeInTheDocument();
+
+ // Fix it.
+ fireEvent.change(input, { target: { value: "512" } });
+ await waitFor(() => {
+ expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+ });
+ });
+ });
+
+ // ── Group 2: Save button disabled state ───────────────────────────────────
+
+ describe("save button disabled state", () => {
+ it("is disabled when chunk size is 0", async () => {
+ renderSection();
+
+ const input = await screen.findByRole("spinbutton", {
+ name: /chunk size/i,
+ });
+ fireEvent.change(input, { target: { value: "0" } });
+
+ expect(
+ screen.getByRole("button", { name: /save ingest settings/i }),
+ ).toBeDisabled();
+ });
+
+ it("is disabled when overlap equals chunk size", async () => {
+ renderSection();
+
+ await screen.findByRole("spinbutton", { name: /chunk size/i });
+ const overlapInput = screen.getByRole("spinbutton", {
+ name: /chunk overlap/i,
+ });
+ fireEvent.change(overlapInput, { target: { value: "1024" } });
+
+ expect(
+ screen.getByRole("button", { name: /save ingest settings/i }),
+ ).toBeDisabled();
+ });
+
+ it("is enabled when settings are valid and dirty (user changed a value)", async () => {
+ renderSection();
+
+ const input = await screen.findByRole("spinbutton", {
+ name: /chunk size/i,
+ });
+ fireEvent.change(input, { target: { value: "512" } });
+
+ await waitFor(() => {
+ expect(
+ screen.getByRole("button", { name: /save ingest settings/i }),
+ ).toBeEnabled();
+ });
+ });
+
+ it("is disabled when form is clean (server values match state)", async () => {
+ renderSection();
+
+ // Wait for settings to load — state now matches server (1024 / 50).
+ await screen.findByRole("spinbutton", { name: /chunk size/i });
+
+ expect(
+ screen.getByRole("button", { name: /save ingest settings/i }),
+ ).toBeDisabled();
+ });
+ });
+
+ // ── Group 3: Save handler blocked ─────────────────────────────────────────
+
+ describe("save handler blocked", () => {
+ it("does not POST /api/settings when chunk size is 0 (button is disabled)", async () => {
+ let postCalled = false;
+ server.use(
+ http.post("/api/settings", () => {
+ postCalled = true;
+ return HttpResponse.json({
+ message: "ok",
+ settings: makeSettings({ show_vlm_settings: false }),
+ });
+ }),
+ );
+
+ renderSection();
+
+ const input = await screen.findByRole("spinbutton", {
+ name: /chunk size/i,
+ });
+ fireEvent.change(input, { target: { value: "0" } });
+
+ const saveButton = screen.getByRole("button", {
+ name: /save ingest settings/i,
+ });
+ expect(saveButton).toBeDisabled();
+ expect(postCalled).toBe(false);
+ });
+ });
+
+ // ── Group 4: userEdited ref prevents background sync overwrite ─────────────
+
+ describe("userEdited ref / background sync", () => {
+ it("background refetch does NOT overwrite user-entered chunk size", async () => {
+ const { queryClient } = renderSection();
+
+ // Wait for initial load.
+ const input = await screen.findByRole("spinbutton", {
+ name: /chunk size/i,
+ });
+ expect(input).toHaveValue(1024);
+
+ // User edits the field → userEdited = true.
+ fireEvent.change(input, { target: { value: "512" } });
+ expect(input).toHaveValue(512);
+
+ // Simulate a background refetch that returns a DIFFERENT valid server
+ // value (999). Returning the same 1024 would let TanStack Query preserve
+ // the settings.knowledge reference via structural sharing, so the guarded
+ // sync effect might never run and the assertion could pass trivially.
+ let refetchCompleted = false;
+ server.use(
+ http.get("/api/settings", () => {
+ refetchCompleted = true;
+ return HttpResponse.json(
+ makeSettings({
+ knowledge: { chunk_size: 999, chunk_overlap: 50 },
+ show_vlm_settings: false,
+ }),
+ );
+ }),
+ );
+
+ await act(async () => {
+ await queryClient.invalidateQueries({ queryKey: ["settings"] });
+ });
+
+ // The refetch really happened and returned new data...
+ expect(refetchCompleted).toBe(true);
+ // ...yet the user's edit must be preserved (not overwritten by 999): the
+ // sync effect should have been short-circuited by
+ // userEditedRef.current === true.
+ expect(
+ screen.getByRole("spinbutton", { name: /chunk size/i }),
+ ).toHaveValue(512);
+ });
+
+ it("resumes background sync after the user reverts an edit back to the saved value", async () => {
+ // Regression test for the sticky-userEdited bug: editing a value and then
+ // changing it back leaves the form clean, so a later server change must
+ // be adopted rather than skipped (which would show stale values and let
+ // Save submit them).
+ const { queryClient } = renderSection();
+
+ const input = await screen.findByRole("spinbutton", {
+ name: /chunk size/i,
+ });
+ expect(input).toHaveValue(1024);
+
+ // Edit, then revert back to the saved value — form is clean again.
+ fireEvent.change(input, { target: { value: "512" } });
+ expect(input).toHaveValue(512);
+ fireEvent.change(input, { target: { value: "1024" } });
+ expect(input).toHaveValue(1024);
+
+ // The server value genuinely changes underneath the (clean) form.
+ let refetchCompleted = false;
+ server.use(
+ http.get("/api/settings", () => {
+ refetchCompleted = true;
+ return HttpResponse.json(
+ makeSettings({
+ knowledge: { chunk_size: 2048, chunk_overlap: 50 },
+ show_vlm_settings: false,
+ }),
+ );
+ }),
+ );
+
+ await act(async () => {
+ await queryClient.invalidateQueries({ queryKey: ["settings"] });
+ });
+
+ expect(refetchCompleted).toBe(true);
+ // Because the form was clean, the resync must adopt the new server value
+ // (2048) instead of leaving the stale 1024.
+ await waitFor(() => {
+ expect(
+ screen.getByRole("spinbutton", { name: /chunk size/i }),
+ ).toHaveValue(2048);
+ });
+ });
+
+ it("background sync resumes after a successful save", async () => {
+ renderSection();
+
+ // Wait for initial load.
+ const input = await screen.findByRole("spinbutton", {
+ name: /chunk size/i,
+ });
+ expect(input).toHaveValue(1024);
+
+ // User edits.
+ fireEvent.change(input, { target: { value: "512" } });
+
+ // Override handlers: POST succeeds, then GET returns a different server
+ // value (999) to prove sync has resumed after the save.
+ server.use(
+ http.post("/api/settings", () =>
+ HttpResponse.json({
+ message: "ok",
+ settings: makeSettings({
+ knowledge: { chunk_size: 512, chunk_overlap: 50 },
+ show_vlm_settings: false,
+ }),
+ }),
+ ),
+ http.get("/api/settings", () =>
+ HttpResponse.json(
+ makeSettings({
+ knowledge: { chunk_size: 999, chunk_overlap: 50 },
+ show_vlm_settings: false,
+ }),
+ ),
+ ),
+ );
+
+ // Trigger the save.
+ fireEvent.click(
+ screen.getByRole("button", { name: /save ingest settings/i }),
+ );
+
+ // After the POST succeeds, userEdited resets to false. The mutation's
+ // own invalidateQueries then fires another GET, which returns 999. The
+ // sync effect (no longer blocked) must update the input.
+ await waitFor(() => {
+ expect(
+ screen.getByRole("spinbutton", { name: /chunk size/i }),
+ ).toHaveValue(999);
+ });
+ });
+ });
+});
diff --git a/frontend/app/settings/_components/ingest-settings-section.tsx b/frontend/app/settings/_components/ingest-settings-section.tsx
index 0a4e80ec5..84799571c 100644
--- a/frontend/app/settings/_components/ingest-settings-section.tsx
+++ b/frontend/app/settings/_components/ingest-settings-section.tsx
@@ -9,6 +9,7 @@ import {
useGetOllamaModelsQuery,
} from "@/app/api/queries/useGetModelsQuery";
import { useGetSettingsQuery } from "@/app/api/queries/useGetSettingsQuery";
+import { getChunkSettingsError } from "@/components/cloud-picker/types";
import { ConfirmationDialog } from "@/components/confirmation-dialog";
import { LabelWrapper } from "@/components/label-wrapper";
import {
@@ -80,9 +81,10 @@ export function IngestSettingsSection() {
const [chunkSize, setChunkSize] = useState<number>(1024);
const [chunkOverlap, setChunkOverlap] = useState<number>(50);
- const [chunkValidationError, setChunkValidationError] = useState<
- string | null
- >(null);
+ const chunkValidationError = getChunkSettingsError({
+ chunkSize,
+ chunkOverlap,
+ });
const [tableStructure, setTableStructure] = useState<boolean>(true);
const [ocr, setOcr] = useState<boolean>(false);
const [pictureDescriptions, setPictureDescriptions] =
@@ -321,7 +323,19 @@ export function IngestSettingsSection() {
handleEmbeddingModelChange,
]);
+ const userEditedRef = useRef(userEdited);
+ userEditedRef.current = userEdited;
+
useEffect(() => {
+ // Skip resync while the user has an unsaved edit in progress — otherwise
+ // a background refetch of settings.knowledge silently overwrites what
+ // they're typing before they've had a chance to save it. Read via a ref
+ // (rather than depending on userEdited directly) so this effect doesn't
+ // re-fire against stale, pre-refetch data the instant a save flips
+ // userEdited back to false. userEdited is cleared as soon as the form
+ // matches the server again (see the effect below useRegisterDirty), so a
+ // value the user edited and then reverted no longer blocks this resync.
+ if (userEditedRef.current) return;
const k = settings.knowledge;
if (!k) return;
if (k.chunk_size !== undefined) setChunkSize(k.chunk_size);
@@ -434,6 +448,18 @@ export function IngestSettingsSection() {
useRegisterDirty("ingest-settings", userEdited && knowledgeIngestDirty);
+ // Keep `userEdited` honest. It is set on every edit but, left alone, would
+ // stay sticky until the next successful save. If the user edits a value and
+ // then reverts it back to what the server has, the form is clean again — but
+ // a sticky flag would (a) permanently skip the resync effect above, so a
+ // genuine later server change is never picked up (stale form), and (b) let
+ // the Save button re-enable and submit that stale value. Clearing the flag
+ // the moment the form matches the server gates the resync on an *actual*
+ // unsaved difference rather than a one-way "has ever edited" flag.
+ useEffect(() => {
+ if (userEdited && !knowledgeIngestDirty) setUserEdited(false);
+ }, [userEdited, knowledgeIngestDirty]);
+
// Resolve through the same map that builds the groups: the catalogue now
// contributes custom LiteLLM providers, so a hard-coded chain would report
// OpenAI's state for any provider outside the four legacy keys.
@@ -451,13 +477,11 @@ export function IngestSettingsSection() {
const handleChunkSizeChange = (value: string) => {
setUserEdited(true);
setChunkSize(Math.max(0, Number.parseInt(value, 10) || 0));
- setChunkValidationError(null);
};
const handleChunkOverlapChange = (value: string) => {
setUserEdited(true);
setChunkOverlap(Math.max(0, Number.parseInt(value, 10) || 0));
- setChunkValidationError(null);
};
const handleKnowledgeIngestSave = () => {
@@ -493,16 +517,10 @@ export function IngestSettingsSection() {
},
});
- if (chunkSize < 1) {
- const msg = "Chunk size must be at least 1";
- setChunkValidationError(msg);
- toast.error("Could not save ingest settings", { description: msg });
- return;
- }
- if (chunkOverlap >= chunkSize) {
- const msg = "Chunk overlap must be less than chunk size";
- setChunkValidationError(msg);
- toast.error("Could not save ingest settings", { description: msg });
+ if (chunkValidationError) {
+ toast.error("Could not save ingest settings", {
+ description: chunkValidationError,
+ });
return;
}
@@ -534,7 +552,6 @@ export function IngestSettingsSection() {
},
{
onSuccess: () => {
- setChunkValidationError(null);
setValidationError(null);
setUserEdited(false);
},
@@ -589,7 +606,6 @@ export function IngestSettingsSection() {
setOcr(DEFAULT_KNOWLEDGE_SETTINGS.ocr);
setPictureDescriptions(DEFAULT_KNOWLEDGE_SETTINGS.picture_descriptions);
setDisableIngestWithLangflow(false);
- setChunkValidationError(null);
setUserEdited(false);
toast.success("Default ingest flow settings restored successfully");
closeDialog();
@@ -1093,7 +1109,8 @@ export function IngestSettingsSection() {
disabled={
updateSettingsMutation.isPending ||
!knowledgeIngestDirty ||
- vlmModelPending
+ vlmModelPending ||
+ !!chunkValidationError
}
className="min-w-[120px]"
size="sm"
diff --git a/frontend/components/cloud-picker/types.test.ts b/frontend/components/cloud-picker/types.test.ts
index 4d8312071..8bc049d07 100644
--- a/frontend/components/cloud-picker/types.test.ts
+++ b/frontend/components/cloud-picker/types.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
-import { describe, it } from "vitest";
-import { getIngestChunkSettingsError } from "./types";
+import { describe, expect, it } from "vitest";
+import { getChunkSettingsError, getIngestChunkSettingsError } from "./types";
const validSettings = {
embeddingModel: "prod-embed",
@@ -32,3 +32,57 @@ describe("getIngestChunkSettingsError", () => {
assert.equal(getIngestChunkSettingsError(validSettings), null);
});
});
+
+describe("getChunkSettingsError", () => {
+ it("returns null for valid settings", () => {
+ expect(
+ getChunkSettingsError({ chunkSize: 1024, chunkOverlap: 50 }),
+ ).toBeNull();
+ });
+
+ it("returns null when overlap is 0", () => {
+ expect(
+ getChunkSettingsError({ chunkSize: 1024, chunkOverlap: 0 }),
+ ).toBeNull();
+ });
+
+ it("returns null when overlap is exactly chunkSize - 1 (boundary)", () => {
+ expect(
+ getChunkSettingsError({ chunkSize: 1024, chunkOverlap: 1023 }),
+ ).toBeNull();
+ });
+
+ it("returns chunk size error when chunkSize is 0", () => {
+ expect(getChunkSettingsError({ chunkSize: 0, chunkOverlap: 0 })).toBe(
+ "Chunk size must be at least 1",
+ );
+ });
+
+ it("returns chunk size error when chunkSize is negative", () => {
+ expect(getChunkSettingsError({ chunkSize: -5, chunkOverlap: 0 })).toBe(
+ "Chunk size must be at least 1",
+ );
+ });
+
+ it("returns overlap error when chunkOverlap equals chunkSize", () => {
+ expect(getChunkSettingsError({ chunkSize: 100, chunkOverlap: 100 })).toBe(
+ "Chunk overlap must be less than chunk size",
+ );
+ });
+
+ it("returns overlap error when chunkOverlap exceeds chunkSize", () => {
+ expect(getChunkSettingsError({ chunkSize: 100, chunkOverlap: 200 })).toBe(
+ "Chunk overlap must be less than chunk size",
+ );
+ });
+
+ it("chunk size error takes priority when both would fire (size=0, overlap=999)", () => {
+ expect(getChunkSettingsError({ chunkSize: 0, chunkOverlap: 999 })).toBe(
+ "Chunk size must be at least 1",
+ );
+ });
+
+ it("returns null for minimum valid config (chunkSize: 1, chunkOverlap: 0)", () => {
+ expect(getChunkSettingsError({ chunkSize: 1, chunkOverlap: 0 })).toBeNull();
+ });
+});
diff --git a/frontend/components/cloud-picker/types.ts b/frontend/components/cloud-picker/types.ts
index f93c63faa..1ff837083 100644
--- a/frontend/components/cloud-picker/types.ts
+++ b/frontend/components/cloud-picker/types.ts
@@ -127,6 +127,13 @@ export function getIngestChunkSettingsError(
if (!settings.embeddingModel.trim()) {
return "Select an embedding model in Settings before ingesting files";
}
+ return getChunkSettingsError(settings);
+}
+
+/** Inline error message if chunk settings are invalid; otherwise null. */
+export function getChunkSettingsError(
+ settings: Pick<IngestSettings, "chunkSize" | "chunkOverlap">,
+): string | null {
if (settings.chunkSize < 1) {
return "Chunk size must be at least 1";
}