Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(v4-migration): show the migration UI by default on dual write mode (#16316)

Steffen Schmitz4277d90a2fd8
diff --git a/web/src/__tests__/organization-settings-pages.clienttest.tsx b/web/src/__tests__/organization-settings-pages.clienttest.tsx
index 43b9816880..51068191c3 100644
--- a/web/src/__tests__/organization-settings-pages.clienttest.tsx
+++ b/web/src/__tests__/organization-settings-pages.clienttest.tsx
@@ -144,7 +144,7 @@ describe("useOrganizationSettingsPages", () => {
);
});
- it("gates the v4 migration link on the v4UpgradeUi flag", () => {
+ it("gates the v4 migration link on deployment availability", () => {
const { result } = renderHook(() => useOrganizationSettingsPages());
expect(
diff --git a/web/src/__tests__/server/userAccount.servertest.ts b/web/src/__tests__/server/userAccount.servertest.ts
index 40b14f3b84..02f1f387dc 100644
--- a/web/src/__tests__/server/userAccount.servertest.ts
+++ b/web/src/__tests__/server/userAccount.servertest.ts
@@ -45,29 +45,6 @@ describe("userAccountRouter.setFeaturePreviewEnabled", () => {
expect(user.featureFlags).toEqual(["templateFlag", "modernSession"]);
});
- it("enables the V4 migration UI preview, leaving other flags intact", async () => {
- const { caller, userId } = await createCaller({
- featureFlags: ["templateFlag"],
- });
-
- const result = await caller.userAccount.setFeaturePreviewEnabled({
- flag: "v4UpgradeUi",
- enabled: true,
- });
-
- expect(result).toEqual({
- success: true,
- flag: "v4UpgradeUi",
- enabled: true,
- });
-
- const user = await prisma.user.findUniqueOrThrow({
- where: { id: userId },
- select: { featureFlags: true },
- });
- expect(user.featureFlags).toEqual(["templateFlag", "v4UpgradeUi"]);
- });
-
it("disables a preview flag without touching the others", async () => {
const { caller, userId } = await createCaller({
featureFlags: ["templateFlag", "modernSession"],
@@ -91,11 +68,11 @@ describe("userAccountRouter.setFeaturePreviewEnabled", () => {
expect(user.featureFlags).toEqual(["templateFlag"]);
});
- "persists an opt-out when %s disables a preview",
- async (email) => {
+ it.each(["langfuse.com", "clickhouse.com"])(
+ "persists an opt-out when a team member on %s disables a preview",
+ async (emailDomain) => {
const { caller, userId } = await createCaller({
- email,
+ emailDomain,
featureFlags: ["templateFlag"],
});
@@ -139,13 +116,15 @@ async function createCaller({
aiFeaturesEnabled = true,
featureFlags = ["templateFlag"],
includeProjectInSession = true,
- email,
+ emailDomain = "example.com",
}: {
plan?: Plan;
aiFeaturesEnabled?: boolean;
featureFlags?: string[];
includeProjectInSession?: boolean;
- email?: string;
+ // Domain only — the local part is always unique so reruns against the same
+ // database do not trip the users.email unique constraint.
+ emailDomain?: string;
} = {}) {
const id = randomUUID();
const orgId = `org-${id}`;
@@ -169,7 +148,7 @@ async function createCaller({
const user = await prisma.user.create({
data: {
id: userId,
- email: email ?? `${userId}@example.com`,
+ email: `${userId}@${emailDomain}`,
name: "User Account Test User",
featureFlags,
},
@@ -212,7 +191,6 @@ async function createCaller({
modernSession: featureFlags.includes("modernSession"),
searchBar: featureFlags.includes("searchBar"),
templateFlag: featureFlags.includes("templateFlag"),
- v4UpgradeUi: featureFlags.includes("v4UpgradeUi"),
excludeClickhouseRead: false,
observationEvals: false,
v4BetaToggleVisible: false,
diff --git a/web/src/components/layouts/app-layout/utils/navigationFilters.ts b/web/src/components/layouts/app-layout/utils/navigationFilters.ts
index 432cbb5414..e40449cfcc 100644
--- a/web/src/components/layouts/app-layout/utils/navigationFilters.ts
+++ b/web/src/components/layouts/app-layout/utils/navigationFilters.ts
@@ -83,12 +83,6 @@ export const filters = {
return ctx.session?.user?.canToggleV4 === true ? route : null;
}
- if (route.featureFlag === "v4UpgradeUi") {
- return ctx.session?.user?.featureFlags.v4UpgradeUi === true
- ? route
- : null;
- }
-
const hasFlag =
ctx.enableExperimentalFeatures ||
ctx.cloudAdmin ||
@@ -177,6 +171,7 @@ export const filters = {
projectId: ctx.routerProjectId,
isLangfuseCloud: ctx.isLangfuseCloud,
v4WriteMode: ctx.session?.environment?.v4WriteMode,
+ v4UpgradeUiAvailable: ctx.session?.user?.v4UpgradeUiAvailable === true,
})
? route
: null;
diff --git a/web/src/components/layouts/routes.tsx b/web/src/components/layouts/routes.tsx
index 5667437fad..3c0ee3ad42 100644
--- a/web/src/components/layouts/routes.tsx
+++ b/web/src/components/layouts/routes.tsx
@@ -68,6 +68,7 @@ export type Route = {
projectId: string | undefined;
isLangfuseCloud: boolean;
v4WriteMode: undefined | "legacy" | "dual" | "events_only"; // undefined until the session has loaded
+ v4UpgradeUiAvailable: boolean; // deployment shows the v4 migration UI (see isV4UpgradeUiAvailable)
}) => boolean;
group?: RouteGroup; // group this route belongs to (within a section)
};
@@ -225,8 +226,8 @@ export const ROUTES: Route[] = [
title: "Update",
pathname: "",
section: RouteSection.Secondary,
- featureFlag: "v4UpgradeUi",
- show: ({ projectId }) => projectId !== undefined,
+ show: ({ projectId, v4UpgradeUiAvailable }) =>
+ v4UpgradeUiAvailable && projectId !== undefined,
menuNode: <V4MigrationNavItem />,
},
{
diff --git a/web/src/features/events/lib/v4Rollout.clienttest.ts b/web/src/features/events/lib/v4Rollout.clienttest.ts
index 81cda4bc38..c4b8caba7f 100644
--- a/web/src/features/events/lib/v4Rollout.clienttest.ts
+++ b/web/src/features/events/lib/v4Rollout.clienttest.ts
@@ -2,7 +2,7 @@
import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { canToggleV4 } from "./v4Rollout";
+import { canToggleV4, isV4UpgradeUiAvailable } from "./v4Rollout";
describe("canToggleV4", () => {
const originalRegion = process.env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION;
@@ -40,3 +40,45 @@ describe("canToggleV4", () => {
).toBe(false);
});
});
+
+describe("isV4UpgradeUiAvailable", () => {
+ // dualPreviewAvailable mirrors auth.ts: Cloud always has it, self-hosted only
+ // with LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN=true.
+ const availability = (
+ isLangfuseCloud: boolean,
+ v4WriteMode: "legacy" | "dual" | "events_only",
+ allowPreviewOptIn = false,
+ ) =>
+ isV4UpgradeUiAvailable({
+ isLangfuseCloud,
+ v4WriteMode,
+ dualPreviewAvailable: isLangfuseCloud || allowPreviewOptIn,
+ });
+
+ it("is on for Langfuse Cloud on dual and events_only", () => {
+ expect(availability(true, "dual")).toBe(true);
+ expect(availability(true, "events_only")).toBe(true);
+ });
+
+ it("is on for a self-hosted dual deployment that allows the preview opt-in", () => {
+ expect(availability(false, "dual", true)).toBe(true);
+ });
+
+ it("is off for a self-hosted dual deployment without the preview opt-in", () => {
+ // Nobody on the deployment can move onto the v4 read path, so every call to
+ // action in the migration UI would be a dead end.
+ expect(availability(false, "dual", false)).toBe(false);
+ });
+
+ it("is off for a self-hosted events_only deployment", () => {
+ // The migration is already over: legacy API routes 404, legacy evaluators
+ // are hidden and the legacy analytics integrations are no-ops.
+ expect(availability(false, "events_only", true)).toBe(false);
+ });
+
+ it("is off on legacy regardless of deployment or opt-in", () => {
+ // The events tables the migration surfaces read are not written.
+ expect(availability(true, "legacy")).toBe(false);
+ expect(availability(false, "legacy", true)).toBe(false);
+ });
+});
diff --git a/web/src/features/events/lib/v4Rollout.ts b/web/src/features/events/lib/v4Rollout.ts
index 82281753e0..1e85b79796 100644
--- a/web/src/features/events/lib/v4Rollout.ts
+++ b/web/src/features/events/lib/v4Rollout.ts
@@ -59,3 +59,50 @@ export function canToggleV4(
return !shouldAutoEnableV4(context);
}
+
+type V4UpgradeUiAvailabilityContext = {
+ isLangfuseCloud: boolean;
+ v4WriteMode: "legacy" | "dual" | "events_only";
+ // Whether a dual-mode deployment lets anyone read through the v4 events
+ // tables: Cloud always does, self-hosted only with
+ // LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN=true.
+ dualPreviewAvailable: boolean;
+};
+
+/**
+ * Whether this deployment shows the v4 migration/upgrade UI (sidebar "Action
+ * required" pill, the per-project chips and banner on the organization
+ * overview, the migration panel and status page) by default.
+ *
+ * This is a different question from `v4BetaEnabled`: the migration UI guides
+ * users through work that is still pending, so it deliberately does not
+ * require the user to have opted into v4 reads first — the panel is where that
+ * opt-in is offered.
+ *
+ * - `legacy`: off. The events tables the migration surfaces read are not
+ * written, so every readiness check would come back unknown.
+ * - `dual`: on, but self-hosted only once the operator set ALLOW_PREVIEW_OPT_IN.
+ * Both table sets are written, so there is a real migration to guide — but
+ * without the opt-in nobody on the deployment can move onto the v4 read path,
+ * which makes every call to action a dead end.
+ * - `events_only`: Cloud only. Self-hosted the migration is already over — the
+ * legacy public API routes 404, legacy evaluators are hidden and the legacy
+ * analytics integrations are no-ops, so nothing is left to act on. On Cloud we
+ * keep it so users still get an explanation once the region flips.
+ *
+ * Per-project exceptions are handled downstream by LANGFUSE_FORCE_V3_EXPERIENCE.
+ */
+export function isV4UpgradeUiAvailable({
+ isLangfuseCloud,
+ v4WriteMode,
+ dualPreviewAvailable,
+}: V4UpgradeUiAvailabilityContext): boolean {
+ switch (v4WriteMode) {
+ case "legacy":
+ return false;
+ case "dual":
+ return dualPreviewAvailable;
+ case "events_only":
+ return isLangfuseCloud;
+ }
+}
diff --git a/web/src/features/feature-flags/available-flags.ts b/web/src/features/feature-flags/available-flags.ts
index 6f278c716c..8741544b05 100644
--- a/web/src/features/feature-flags/available-flags.ts
+++ b/web/src/features/feature-flags/available-flags.ts
@@ -7,7 +7,6 @@ export const featurePreviewFlags = [
// no longer a per-user Feature Preview opt-in. Kept as dead plumbing for a
// safe rollback; drop once the GA rollout is confirmed stable.
"searchBar",
- "v4UpgradeUi",
"compactTimeline",
] as const;
@@ -29,10 +28,6 @@ export const isFeaturePreviewAvailable = (
return true;
}
- if (flag === "v4UpgradeUi") {
- return true;
- }
-
if (flag === "compactTimeline") {
return true;
}
diff --git a/web/src/features/feature-flags/types.ts b/web/src/features/feature-flags/types.ts
index 567557680a..32c0ab9fa1 100644
--- a/web/src/features/feature-flags/types.ts
+++ b/web/src/features/feature-flags/types.ts
@@ -2,13 +2,9 @@ import { type availableFlags } from "./available-flags";
export type Flag = (typeof availableFlags)[number];
export type Flags = {
- [key in Exclude<
- Flag,
- "modernSession" | "v4UpgradeUi" | "compactTimeline"
- >]: boolean;
+ [key in Exclude<Flag, "modernSession" | "compactTimeline">]: boolean;
} & {
// Optional while older sessions and test fixtures roll across new flags.
modernSession?: boolean;
- v4UpgradeUi?: boolean;
compactTimeline?: boolean;
};
diff --git a/web/src/features/feature-previews/components/ControlledFeaturePreviewModal.tsx b/web/src/features/feature-previews/components/ControlledFeaturePreviewModal.tsx
index 7421a144de..9e49d499ca 100644
--- a/web/src/features/feature-previews/components/ControlledFeaturePreviewModal.tsx
+++ b/web/src/features/feature-previews/components/ControlledFeaturePreviewModal.tsx
@@ -20,7 +20,6 @@ type ControlledFeaturePreviewModalProps = {
const PREVIEW_LABEL: Record<PreviewFlag, string> = {
modernSession: "Compact Session View",
searchBar: "Filter Search Bar",
- v4UpgradeUi: "V4 Migration",
compactTimeline: "Compact Timeline",
};
@@ -70,11 +69,6 @@ export function ControlledFeaturePreviewModal({
onToggle: onToggle("modernSession"),
isToggling: setFeaturePreviewEnabled.isPending,
},
- v4UpgradeUi: {
- enabled: authSession.data?.user?.featureFlags.v4UpgradeUi === true,
- onToggle: onToggle("v4UpgradeUi"),
- isToggling: setFeaturePreviewEnabled.isPending,
- },
compactTimeline: {
enabled:
authSession.data?.user?.featureFlags.compactTimeline === true ||
diff --git a/web/src/features/feature-previews/components/FeaturePreviewModal.stories.tsx b/web/src/features/feature-previews/components/FeaturePreviewModal.stories.tsx
index 4eb59288e7..fbf43e9ad2 100644
--- a/web/src/features/feature-previews/components/FeaturePreviewModal.stories.tsx
+++ b/web/src/features/feature-previews/components/FeaturePreviewModal.stories.tsx
@@ -57,7 +57,6 @@ const meta = preview.meta({
onOpenChange: fn(),
state: {
modernSession: { enabled: false, onToggle: fn(), isToggling: false },
- v4UpgradeUi: { enabled: false, onToggle: fn(), isToggling: false },
},
},
render: StatefulFeaturePreviewModal,
diff --git a/web/src/features/feature-previews/components/FeaturePreviewModal.tsx b/web/src/features/feature-previews/components/FeaturePreviewModal.tsx
index f7f453e872..848360dd42 100644
--- a/web/src/features/feature-previews/components/FeaturePreviewModal.tsx
+++ b/web/src/features/feature-previews/components/FeaturePreviewModal.tsx
@@ -89,23 +89,6 @@ const PREVIEW_REGISTRY: PreviewRegistryItem[] = [
alt: "A whole trace as dense coloured lines, one per observation, cascading across a time axis.",
},
},
- {
- flag: "v4UpgradeUi",
- title: "V4 Migration",
- sidebarLabel: "V4 Migration",
- description:
- "Review each project's readiness for Langfuse v4 and get guided steps for anything that still needs an update.",
- details:
- "The V4 Migration experience adds a migration status page, project-level readiness indicators, and contextual upgrade guidance for SDKs, evaluators, deprecated APIs, and integrations.",
- feedbackUrl: "https://github.com/orgs/langfuse/discussions",
- illustration: {
- light: "/assets/v4-beta-intro.jpg",
- dark: "/assets/v4-beta-intro.jpg",
- alt: "Langfuse v4 performance improvements across common observability workflows.",
- width: 1024,
- height: 598,
- },
- },
// TODO(remove ~2026-06-19): dead registry entry — "searchBar" is GA on the v4
// events tables and no longer surfaced in the dialog (no state entry in
// ControlledFeaturePreviewModal), so this is filtered out and never renders.
diff --git a/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx b/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx
index 70890ab88e..000c1757fe 100644
--- a/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx
+++ b/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx
@@ -1222,6 +1222,22 @@ describe("V4MigrationHeaderContent", () => {
).toHaveAttribute("href", "https://langfuse.com/docs/v4#timeline");
});
+ it("drops the dated deadline for self-hosted deployments", () => {
+ // The date is a Cloud commitment: a self-hosted deployment keeps its legacy
+ // surfaces until its own operator moves the write mode off dual.
+ mocks.env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION = undefined;
+
+ render(<V4MigrationHeaderContent readiness="action-needed" />);
+
+ expect(screen.getByText(/features may stop working/)).toHaveTextContent(
+ "Some features may stop working without an upgrade once your administrator disables the legacy mode.",
+ );
+ expect(screen.queryByText(/November 16, 2026/)).not.toBeInTheDocument();
+ expect(
+ screen.queryByRole("link", { name: "November 16, 2026" }),
+ ).not.toBeInTheDocument();
+ });
+
it("reserves a close-button gutter on the title row when the host asks", () => {
// The modal host floats the dialog's fallback close button over the
// body's top-right corner; without the gutter it overlaps the title.
diff --git a/web/src/features/v4-migration/V4MigrationContent.tsx b/web/src/features/v4-migration/V4MigrationContent.tsx
index 572967d785..3a4193de89 100644
--- a/web/src/features/v4-migration/V4MigrationContent.tsx
+++ b/web/src/features/v4-migration/V4MigrationContent.tsx
@@ -11,6 +11,7 @@ import {
} from "lucide-react";
import { env } from "@/src/env.mjs";
import { useIsInAppAgentLauncherVisible } from "@/src/features/in-app-agent/components/InAppAiAgentProvider";
+import { useLangfuseCloudRegion } from "@/src/features/organizations/hooks";
import { useSupportDrawer } from "@/src/features/support-chat/SupportDrawerProvider";
import { Button } from "@/src/components/ui/button";
import {
@@ -1039,6 +1040,19 @@ export function V4MigrationIntegrationsSection({
);
}
+/**
+ * Whether this deployment is bound by the dated v3 sunset.
+ *
+ * `V4_MIGRATION_DEADLINE` is a Langfuse Cloud commitment. On a self-hosted
+ * deployment nothing happens on that date — the legacy surfaces keep working
+ * until the operator moves the write mode off `dual`, so quoting a date would
+ * be plainly wrong. The Fern deprecation messages scope the same date to Cloud
+ * for the same reason (see `deprecations.ts`).
+ */
+export function useHasV4MigrationDeadline(): boolean {
+ return useLangfuseCloudRegion().isLangfuseCloud;
+}
+
// Docs link and deadline note are shared by the panel/modal header and the
// account-level status page so both surfaces read the same.
export function V4MigrationDocsLink() {
@@ -1053,6 +1067,17 @@ export function V4MigrationDocsLink() {
}
export function V4MigrationDeadlineNote() {
+ const hasDeadline = useHasV4MigrationDeadline();
+
+ if (!hasDeadline) {
+ return (
+ <p>
+ Some features may stop working without an upgrade once your
+ administrator disables the legacy mode.
+ </p>
+ );
+ }
+
return (
<p>
After{" "}
diff --git a/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx b/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx
index e911d68ab4..f0fc01e4c8 100644
--- a/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx
+++ b/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx
@@ -25,6 +25,8 @@ const mocks = vi.hoisted(() => ({
lastTracePending: false,
canToggleV4: true,
isBetaEnabled: false,
+ // Cloud is bound by the dated v3 sunset; self-hosted is not.
+ hasDeadline: true,
}));
vi.mock("next/router", () => ({
@@ -76,6 +78,7 @@ vi.mock("@/src/features/in-app-agent/components/InAppAiAgentProvider", () => ({
vi.mock("@/src/features/v4-migration/V4MigrationContent", () => ({
V4_MIGRATION_DEADLINE: "November 16, 2026",
useCopyMigrationPrompt: () => vi.fn(),
+ useHasV4MigrationDeadline: () => mocks.hasDeadline,
// Stand-ins for the shared sidebar copy: the real components are covered in
// V4MigrationContent.clienttest.tsx, here we only assert they are rendered.
V4MigrationDocsLink: () => (
@@ -161,6 +164,7 @@ describe("V4MigrationStatusPage", () => {
mocks.evalCount = 1;
mocks.lastTracePending = false;
mocks.canToggleV4 = true;
+ mocks.hasDeadline = true;
mocks.isBetaEnabled = false;
});
@@ -300,6 +304,36 @@ describe("V4MigrationStatusPage", () => {
expect(screen.queryByText(/Oct 9/)).not.toBeInTheDocument();
});
+ it("replaces the FAQ deadline with the operator cutoff when self-hosted", () => {
+ // Nothing happens to a self-hosted deployment on the Cloud sunset date, so
+ // the FAQ has to point at the operator's own write-mode switch instead.
+ mocks.hasDeadline = false;
+
+ render(<V4MigrationStatusPage />);
+
+ expect(
+ screen.getByText("once your administrator disables the legacy mode"),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByText("Once your administrator disables the legacy mode"),
+ ).toBeInTheDocument();
+ expect(screen.queryByText(/on November 16, 2026/)).not.toBeInTheDocument();
+ expect(screen.queryByText(/On November 16, 2026/)).not.toBeInTheDocument();
+ });
+
+ it("drops the dated sunset from the switch-back warning when self-hosted", () => {
+ mocks.isBetaEnabled = true;
+ mocks.hasDeadline = false;
+
+ render(<V4MigrationStatusPage />);
+
+ expect(
+ screen.getByText(
+ /The features powering the legacy v3 UI will be sunset once your administrator disables the legacy mode\./,
+ ),
+ ).toBeInTheDocument();
+ });
+
it("only shows the status pill when action is required", () => {
mocks.evalCount = 0;
mocks.sdk = {
diff --git a/web/src/features/v4-migration/V4MigrationStatusPage.tsx b/web/src/features/v4-migration/V4MigrationStatusPage.tsx
index 39b0deb0d8..259440d935 100644
--- a/web/src/features/v4-migration/V4MigrationStatusPage.tsx
+++ b/web/src/features/v4-migration/V4MigrationStatusPage.tsx
@@ -15,6 +15,7 @@ import {
} from "@/src/components/ui/table";
import {
useCopyMigrationPrompt,
+ useHasV4MigrationDeadline,
V4MigrationDeadlineNote,
V4MigrationDocsLink,
V4_MIGRATION_DEADLINE,
@@ -474,6 +475,7 @@ export default function V4MigrationStatusPage() {
function V4MigrationStatusPageContent() {
const session = useSession();
const handleCopyPrompt = useCopyMigrationPrompt();
+ const hasDeadline = useHasV4MigrationDeadline();
const orgs: V4MigrationOrganization[] =
session.data?.user?.organizations?.map((org) => ({
@@ -532,8 +534,13 @@ function V4MigrationStatusPageContent() {
Yes, eventually. The{" "}
<FaqLink href={SDK_UPGRADE_URL}>old SDKs</FaqLink>, trace-level evals,
and APIs are frozen and stop working{" "}
- <span className="underline">on {V4_MIGRATION_DEADLINE}</span>. They
- keep running until then, but we&apos;re no longer fixing bugs in them.
+ <span className="underline">
+ {hasDeadline
+ ? `on ${V4_MIGRATION_DEADLINE}`
+ : "once your administrator disables the legacy mode"}
+ </span>
+ . They keep running until then, but we&apos;re no longer fixing bugs
+ in them.
</>
),
},
@@ -558,8 +565,12 @@ function V4MigrationStatusPageContent() {
q: "What if I do nothing?",
a: (
<>
- <span className="underline">On {V4_MIGRATION_DEADLINE}</span>, old
- SDKs stop sending data, and the{" "}
+ <span className="underline">
+ {hasDeadline
+ ? `On ${V4_MIGRATION_DEADLINE}`
+ : "Once your administrator disables the legacy mode"}
+ </span>
+ , old SDKs stop sending data, and the{" "}
<FaqLink href={API_REFERENCE_URL}>
deprecated evals and endpoints
</FaqLink>{" "}
@@ -690,6 +701,7 @@ function V4MigrationStatusPageContent() {
// mode, post-rollout auto-enrollment).
function SwitchBackSection() {
const { canToggleV4, isBetaEnabled } = useV4Beta();
+ const hasDeadline = useHasV4MigrationDeadline();
if (!canToggleV4) {
return null;
@@ -705,9 +717,11 @@ function SwitchBackSection() {
<div className="flex flex-col gap-4 pt-4">
{isBetaEnabled && (
<p className="text-muted-foreground text-sm leading-relaxed">
- The features powering the legacy v3 UI will be sunset on{" "}
- {V4_MIGRATION_DEADLINE}. We strongly recommend switching to the
- latest UI (v4) before then.
+ The features powering the legacy v3 UI will be sunset{" "}
+ {hasDeadline
+ ? `on ${V4_MIGRATION_DEADLINE}`
+ : "once your administrator disables the legacy mode"}
+ . We strongly recommend switching to the latest UI (v4) before then.
</p>
)}
<V4PreviewToggleRow />
diff --git a/web/src/features/v4-migration/useV4UpgradeUiEnabled.clienttest.ts b/web/src/features/v4-migration/useV4UpgradeUiEnabled.clienttest.ts
index 9919e0b0a0..4a2ea8a4cf 100644
--- a/web/src/features/v4-migration/useV4UpgradeUiEnabled.clienttest.ts
+++ b/web/src/features/v4-migration/useV4UpgradeUiEnabled.clienttest.ts
@@ -4,7 +4,6 @@ import { vi } from "vitest";
import { useV4UpgradeUiEnabled } from "./useV4UpgradeUiEnabled";
import { useForceV3Experience } from "./useForceV3Experience";
-import { parseFlags } from "@/src/features/feature-flags/utils";
vi.mock("next-auth/react", () => ({
useSession: vi.fn(),
@@ -17,13 +16,10 @@ vi.mock("./useForceV3Experience", () => ({
const mockUseSession = vi.mocked(useSession);
const mockUseForceV3Experience = vi.mocked(useForceV3Experience);
-const mockSessionFlag = (v4UpgradeUi: boolean) => {
+const mockSessionAvailability = (v4UpgradeUiAvailable: boolean) => {
mockUseSession.mockReturnValue({
data: {
- user: {
- admin: false,
- featureFlags: { v4UpgradeUi },
- },
+ user: { admin: false, featureFlags: {}, v4UpgradeUiAvailable },
environment: { enableExperimentalFeatures: false },
},
} as never);
@@ -34,19 +30,26 @@ describe("useV4UpgradeUiEnabled", () => {
mockUseForceV3Experience.mockReturnValue(false);
});
- it("maps the database flag into the session flag shape", () => {
- const context = { email: undefined, v4BetaEnabled: false };
- expect(parseFlags(["v4UpgradeUi"], context).v4UpgradeUi).toBe(true);
- expect(parseFlags([], context).v4UpgradeUi).toBe(false);
+ it("enables the UI when the deployment can act on the migration", () => {
+ mockSessionAvailability(true);
+
+ const { result } = renderHook(() => useV4UpgradeUiEnabled());
+
+ expect(result.current).toBe(true);
+ });
+
+ it("stays disabled when the deployment cannot act on the migration", () => {
+ mockSessionAvailability(false);
+
+ const { result } = renderHook(() => useV4UpgradeUiEnabled());
+
+ expect(result.current).toBe(false);
});
it("does not enable the UI for admins or experimental deployments", () => {
mockUseSession.mockReturnValue({
data: {
- user: {
- admin: true,
- featureFlags: { v4UpgradeUi: false },
- },
+ user: { admin: true, featureFlags: {}, v4UpgradeUiAvailable: false },
environment: { enableExperimentalFeatures: true },
},
} as never);
@@ -56,29 +59,27 @@ describe("useV4UpgradeUiEnabled", () => {
expect(result.current).toBe(false);
});
- it("enables the UI only when the user flag is set", () => {
- mockSessionFlag(true);
+ it("treats a session without the field as unavailable", () => {
+ // Older sessions and test fixtures predate the field; default to off rather
+ // than showing migration surfaces a deployment may not support.
+ mockUseSession.mockReturnValue({
+ data: {
+ user: { admin: false, featureFlags: {} },
+ environment: { enableExperimentalFeatures: false },
+ },
+ } as never);
const { result } = renderHook(() => useV4UpgradeUiEnabled());
- expect(result.current).toBe(true);
+ expect(result.current).toBe(false);
});
it("suppresses the UI for projects forced onto the v3 experience", () => {
- mockSessionFlag(true);
+ mockSessionAvailability(true);
mockUseForceV3Experience.mockReturnValue(true);
const { result } = renderHook(() => useV4UpgradeUiEnabled());
expect(result.current).toBe(false);
});
-
- it("stays disabled when the flag is off regardless of force-v3", () => {
- mockSessionFlag(false);
- mockUseForceV3Experience.mockReturnValue(false);
-
- const { result } = renderHook(() => useV4UpgradeUiEnabled());
-
- expect(result.current).toBe(false);
- });
});
diff --git a/web/src/features/v4-migration/useV4UpgradeUiEnabled.ts b/web/src/features/v4-migration/useV4UpgradeUiEnabled.ts
index db114a64e3..ec0c07f419 100644
--- a/web/src/features/v4-migration/useV4UpgradeUiEnabled.ts
+++ b/web/src/features/v4-migration/useV4UpgradeUiEnabled.ts
@@ -3,12 +3,14 @@ import { useSession } from "next-auth/react";
import { useForceV3Experience } from "@/src/features/v4-migration/useForceV3Experience";
/**
- * Raw `v4UpgradeUi` feature-preview flag, without the force-v3 suppression.
+ * Whether this deployment shows the v4 migration UI at all, before the
+ * per-project force-v3 suppression. Derived from the write mode once in the
+ * auth session callback — see isV4UpgradeUiAvailable.
*/
export function useV4UpgradeUiFlag(): boolean {
const { data: session } = useSession();
- return session?.user?.featureFlags.v4UpgradeUi === true;
+ return session?.user?.v4UpgradeUiAvailable === true;
}
/**
@@ -19,7 +21,7 @@ export function useV4UpgradeUiFlag(): boolean {
* when the migration UI is off.
*/
export function useV4UpgradeUiEnabled(projectId?: string): boolean {
- const flag = useV4UpgradeUiFlag();
+ const available = useV4UpgradeUiFlag();
const forceV3 = useForceV3Experience(projectId);
- return flag && !forceV3;
+ return available && !forceV3;
}
diff --git a/web/src/server/auth.ts b/web/src/server/auth.ts
index a12e5cd5ab..93c3e2cdd2 100644
--- a/web/src/server/auth.ts
+++ b/web/src/server/auth.ts
@@ -71,7 +71,10 @@ import {
} from "@/src/features/entitlements/server/getPlan";
import { getSSOBlockedDomains } from "@/src/features/auth-credentials/server/signupApiHandler";
import { createSupportEmailHash } from "@/src/features/support-chat/createSupportEmailHash";
-import { canToggleV4 } from "@/src/features/events/lib/v4Rollout";
+import {
+ canToggleV4,
+ isV4UpgradeUiAvailable,
+} from "@/src/features/events/lib/v4Rollout";
import { canCreateOrganizations } from "@/src/features/organizations/server/canCreateOrganizations";
const staticProviders: Provider[] = [
@@ -875,6 +878,15 @@ export async function getAuthOptions(signupAttribution?: {
(v4WriteMode === "dual" &&
dualPreviewAvailable &&
dbUser?.v4BetaEnabled === true);
+ // The migration/upgrade UI is a separate question from the preview
+ // read path above: it guides users through work that is still
+ // pending, so it does not require the user to have opted into v4
+ // reads first — the migration panel is where that opt-in is offered.
+ const v4UpgradeUiAvailable = isV4UpgradeUiAvailable({
+ isLangfuseCloud,
+ v4WriteMode,
+ dualPreviewAvailable,
+ });
return {
...session,
@@ -900,6 +912,7 @@ export async function getAuthOptions(signupAttribution?: {
image: dbUser.image,
admin: dbUser.admin,
v4BetaEnabled,
+ v4UpgradeUiAvailable,
canToggleV4:
v4WriteMode === "dual" && dualPreviewAvailable
? isLangfuseCloud
diff --git a/web/types/next-auth.d.ts b/web/types/next-auth.d.ts
index fca450e8ab..bdb0310791 100644
--- a/web/types/next-auth.d.ts
+++ b/web/types/next-auth.d.ts
@@ -26,6 +26,12 @@ declare module "next-auth" {
admin?: PrismaUser["admin"];
v4BetaEnabled?: boolean;
canToggleV4?: boolean;
+ // Whether this deployment shows the v4 migration UI (sidebar pill,
+ // organization-overview chips and banner, panel, status page). Derived
+ // from the write mode in the session callback — see
+ // isV4UpgradeUiAvailable. This is the gate every migration surface
+ // reads, via useV4UpgradeUiEnabled; there is no per-user opt-in.
+ v4UpgradeUiAvailable?: boolean;
emailVerified?: string | null; // iso datetime string, need to stringify as JWT & useSession do not support Date objects
canCreateOrganizations: boolean; // default true, allowlist can be set via LANGFUSE_ALLOWED_ORGANIZATION_CREATORS
organizations: {