Skip to content

πŸͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat: introduce forced v3 experience for projects integrating through 3rd party providers on legacy SDKs (#16046)

marliessophie0f720df3164b
diff --git a/packages/shared/src/env.ts b/packages/shared/src/env.ts
index c17cd7ca9d..f92e4e7e78 100644
--- a/packages/shared/src/env.ts
+++ b/packages/shared/src/env.ts
@@ -226,6 +226,11 @@ const EnvSchema = z.object({
.string()
.optional()
.transform((s) => (s ? s.split(",").map((id) => id.trim()) : [])),
+ // Has no effect in events_only mode, where the v3 experience cannot work.
+ LANGFUSE_FORCE_V3_EXPERIENCE: z
+ .string()
+ .optional()
+ .transform((s) => (s ? s.split(",").map((id) => id.trim()) : [])),
SALT: z.string().optional(), // used by components imported by web package
LANGFUSE_LOG_LEVEL: z
.enum(["trace", "debug", "info", "warn", "error", "fatal"])
diff --git a/packages/shared/src/server/forceV3Experience.ts b/packages/shared/src/server/forceV3Experience.ts
new file mode 100644
index 0000000000..3165e7c7bc
--- /dev/null
+++ b/packages/shared/src/server/forceV3Experience.ts
@@ -0,0 +1,12 @@
+import { env } from "../env";
+
+/**
+ * Projects listed in LANGFUSE_FORCE_V3_EXPERIENCE keep the legacy (v3)
+ * experience: the old eval experience (trace-level evaluator create/update
+ * stays available) and none of the v4 migration/upgrade UI. Set only on Cloud
+ * for projects instrumented via integration partners that have not upgraded to
+ * OTEL ingestion yet.
+ */
+export function isForceV3ExperienceProject(projectId: string): boolean {
+ return env.LANGFUSE_FORCE_V3_EXPERIENCE.includes(projectId);
+}
diff --git a/packages/shared/src/server/index.ts b/packages/shared/src/server/index.ts
index 814d0232af..3f9d7434e4 100644
--- a/packages/shared/src/server/index.ts
+++ b/packages/shared/src/server/index.ts
@@ -173,6 +173,7 @@ export * from "./utils/headerUtils";
export * from "./utils/formatAuthProvider";
export * from "./traceDeletionProcessor";
export * from "./deletionGuard";
+export * from "./forceV3Experience";
export * from "./analytics-integrations/types";
// Re-annotate these deprecated routing wrappers at the public server barrel.
diff --git a/web/src/__tests__/server/evals-trpc.servertest.ts b/web/src/__tests__/server/evals-trpc.servertest.ts
index ab1e6b0414..9b0d3ff1c1 100644
--- a/web/src/__tests__/server/evals-trpc.servertest.ts
+++ b/web/src/__tests__/server/evals-trpc.servertest.ts
@@ -1,14 +1,19 @@
import { beforeEach, vi } from "vitest";
import type * as SharedEnvModule from "@langfuse/shared/src/env";
-const { runCodeEvalTestForJobConfigMock } = vi.hoisted(() => {
- process.env.LANGFUSE_CODE_EVAL_DISPATCHER = "insecure-local";
- process.env.LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN = "true";
-
- return {
- runCodeEvalTestForJobConfigMock: vi.fn(),
- };
-});
+const { runCodeEvalTestForJobConfigMock, forceV3ProjectIds } = vi.hoisted(
+ () => {
+ process.env.LANGFUSE_CODE_EVAL_DISPATCHER = "insecure-local";
+ process.env.LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN = "true";
+
+ return {
+ runCodeEvalTestForJobConfigMock: vi.fn(),
+ // Mutable backing for the mocked LANGFUSE_FORCE_V3_EXPERIENCE list so
+ // individual tests can force a project onto the v3 experience.
+ forceV3ProjectIds: { current: [] as string[] },
+ };
+ },
+);
vi.mock("@langfuse/shared/src/env", async (importOriginal) => {
const actual = await importOriginal<typeof SharedEnvModule>();
@@ -19,6 +24,9 @@ vi.mock("@langfuse/shared/src/env", async (importOriginal) => {
...actual.env,
LANGFUSE_CODE_EVAL_DISPATCHER: "insecure-local",
NEXT_PUBLIC_LANGFUSE_CLOUD_REGION: undefined,
+ get LANGFUSE_FORCE_V3_EXPERIENCE() {
+ return forceV3ProjectIds.current;
+ },
},
};
});
@@ -56,6 +64,7 @@ import type { Session } from "next-auth";
import { env } from "@/src/env.mjs";
beforeEach(() => {
+ forceV3ProjectIds.current = [];
runCodeEvalTestForJobConfigMock.mockReset();
runCodeEvalTestForJobConfigMock.mockResolvedValue({
success: true,
@@ -1047,25 +1056,34 @@ describe("evals trpc", () => {
},
});
- await expect(
- caller.evals.createJob({
- projectId: project.id,
- evalTemplateId: evalTemplate.id,
- scoreName: "bad-trace-score",
- target: EvalTargetObject.TRACE,
- filter: [],
- mapping: [
- {
- templateVariable: "input",
- selectedColumnId: "input",
- jsonSelector: null,
- },
- ],
- sampling: 1,
- delay: 0,
- timeScope: ["NEW"],
- }),
- ).rejects.toThrow("Variable mapping does not match evaluator target.");
+ // Open the legacy-target gate (the .env test config is Cloud + dual) so
+ // this test reaches the variable-mapping validation behind it.
+ const originalWriteMode = env.LANGFUSE_MIGRATION_V4_WRITE_MODE;
+ Reflect.set(env, "LANGFUSE_MIGRATION_V4_WRITE_MODE", "legacy");
+
+ try {
+ await expect(
+ caller.evals.createJob({
+ projectId: project.id,
+ evalTemplateId: evalTemplate.id,
+ scoreName: "bad-trace-score",
+ target: EvalTargetObject.TRACE,
+ filter: [],
+ mapping: [
+ {
+ templateVariable: "input",
+ selectedColumnId: "input",
+ jsonSelector: null,
+ },
+ ],
+ sampling: 1,
+ delay: 0,
+ timeScope: ["NEW"],
+ }),
+ ).rejects.toThrow("Variable mapping does not match evaluator target.");
+ } finally {
+ Reflect.set(env, "LANGFUSE_MIGRATION_V4_WRITE_MODE", originalWriteMode);
+ }
await expect(
prisma.jobConfiguration.findFirst({
@@ -1093,29 +1111,122 @@ describe("evals trpc", () => {
},
});
- await expect(
- caller.evals.createJob({
- projectId: project.id,
- evalTemplateId: evalTemplate.id,
- scoreName: "bad-trace-filter",
- target: EvalTargetObject.TRACE,
- filter: [
- {
- type: "numberObject",
- column: "Scores (numeric)",
- key: "accuracy",
- operator: ">",
- value: 0.8,
- },
- ],
- mapping: [],
- sampling: 1,
- delay: 0,
- timeScope: ["NEW"],
- }),
- ).rejects.toThrow(
- 'Filter column "Scores (numeric)" is not supported for target "trace".',
- );
+ // Open the legacy-target gate (the .env test config is Cloud + dual) so
+ // this test reaches the filter validation behind it.
+ const originalWriteMode = env.LANGFUSE_MIGRATION_V4_WRITE_MODE;
+ Reflect.set(env, "LANGFUSE_MIGRATION_V4_WRITE_MODE", "legacy");
+
+ try {
+ await expect(
+ caller.evals.createJob({
+ projectId: project.id,
+ evalTemplateId: evalTemplate.id,
+ scoreName: "bad-trace-filter",
+ target: EvalTargetObject.TRACE,
+ filter: [
+ {
+ type: "numberObject",
+ column: "Scores (numeric)",
+ key: "accuracy",
+ operator: ">",
+ value: 0.8,
+ },
+ ],
+ mapping: [],
+ sampling: 1,
+ delay: 0,
+ timeScope: ["NEW"],
+ }),
+ ).rejects.toThrow(
+ 'Filter column "Scores (numeric)" is not supported for target "trace".',
+ );
+ } finally {
+ Reflect.set(env, "LANGFUSE_MIGRATION_V4_WRITE_MODE", originalWriteMode);
+ }
+ });
+ });
+
+ describe("evals.createJob legacy target gate", () => {
+ const createTraceTemplate = (projectId: string) =>
+ prisma.evalTemplate.create({
+ data: {
+ projectId,
+ name: `trace-gate-template-${projectId}`,
+ version: 1,
+ prompt: "Score {{input}}",
+ vars: ["input"],
+ outputDefinition: createNumericEvalOutputDefinition({
+ reasoningDescription: "Why",
+ scoreDescription: "How good",
+ }),
+ },
+ });
+
+ const traceMapping = [
+ {
+ templateVariable: "input",
+ langfuseObject: "trace",
+ objectName: null,
+ selectedColumnId: "input",
+ jsonSelector: null,
+ },
+ ];
+
+ it("rejects new trace-target evaluators when the legacy experience is disabled", async () => {
+ const { project, caller } = await prepare();
+ const originalMode = env.LANGFUSE_MIGRATION_V4_WRITE_MODE;
+ Reflect.set(env, "LANGFUSE_MIGRATION_V4_WRITE_MODE", "events_only");
+
+ try {
+ const template = await createTraceTemplate(project.id);
+ await expect(
+ caller.evals.createJob({
+ projectId: project.id,
+ evalTemplateId: template.id,
+ scoreName: "gate-closed-score",
+ target: EvalTargetObject.TRACE,
+ filter: [],
+ mapping: traceMapping,
+ sampling: 1,
+ delay: 0,
+ timeScope: ["NEW"],
+ }),
+ ).rejects.toThrow("Trace- and dataset-level evaluators are no longer");
+
+ await expect(
+ prisma.jobConfiguration.findFirst({
+ where: { projectId: project.id, scoreName: "gate-closed-score" },
+ }),
+ ).resolves.toBeNull();
+ } finally {
+ Reflect.set(env, "LANGFUSE_MIGRATION_V4_WRITE_MODE", originalMode);
+ }
+ });
+
+ it("rejects new trace-target evaluators for force-v3 projects in events_only mode", async () => {
+ const { project, caller } = await prepare();
+ const originalMode = env.LANGFUSE_MIGRATION_V4_WRITE_MODE;
+ Reflect.set(env, "LANGFUSE_MIGRATION_V4_WRITE_MODE", "events_only");
+ forceV3ProjectIds.current = [project.id];
+
+ try {
+ const template = await createTraceTemplate(project.id);
+ await expect(
+ caller.evals.createJob({
+ projectId: project.id,
+ evalTemplateId: template.id,
+ scoreName: "gate-forced-score",
+ target: EvalTargetObject.TRACE,
+ filter: [],
+ mapping: traceMapping,
+ sampling: 1,
+ delay: 0,
+ timeScope: ["NEW"],
+ }),
+ ).rejects.toThrow("Trace- and dataset-level evaluators are no longer");
+ } finally {
+ Reflect.set(env, "LANGFUSE_MIGRATION_V4_WRITE_MODE", originalMode);
+ }
});
});
diff --git a/web/src/__tests__/server/unit/legacyEvalGate.servertest.ts b/web/src/__tests__/server/unit/legacyEvalGate.servertest.ts
new file mode 100644
index 0000000000..0a4fa1acdf
--- /dev/null
+++ b/web/src/__tests__/server/unit/legacyEvalGate.servertest.ts
@@ -0,0 +1,62 @@
+import { isNewLegacyEvalAllowed } from "@/src/features/evals/utils/legacyEvalGate";
+
+describe("isNewLegacyEvalAllowed", () => {
+ it("blocks new legacy evals in events_only mode", () => {
+ expect(
+ isNewLegacyEvalAllowed({
+ v4WriteMode: "events_only",
+ isLangfuseCloud: false,
+ isForceV3Project: false,
+ }),
+ ).toBe(false);
+ });
+
+ it("blocks new legacy evals on Cloud in dual mode", () => {
+ expect(
+ isNewLegacyEvalAllowed({
+ v4WriteMode: "dual",
+ isLangfuseCloud: true,
+ isForceV3Project: false,
+ }),
+ ).toBe(false);
+ });
+
+ it("allows new legacy evals on self-hosted dual and legacy modes", () => {
+ expect(
+ isNewLegacyEvalAllowed({
+ v4WriteMode: "dual",
+ isLangfuseCloud: false,
+ isForceV3Project: false,
+ }),
+ ).toBe(true);
+ expect(
+ isNewLegacyEvalAllowed({
+ v4WriteMode: "legacy",
+ isLangfuseCloud: false,
+ isForceV3Project: false,
+ }),
+ ).toBe(true);
+ });
+
+ it("allows new legacy evals for forced-v3 projects while legacy writes exist", () => {
+ for (const v4WriteMode of ["dual", "legacy"] as const) {
+ expect(
+ isNewLegacyEvalAllowed({
+ v4WriteMode,
+ isLangfuseCloud: true,
+ isForceV3Project: true,
+ }),
+ ).toBe(true);
+ }
+ });
+
+ it("blocks forced-v3 projects in events_only mode", () => {
+ expect(
+ isNewLegacyEvalAllowed({
+ v4WriteMode: "events_only",
+ isLangfuseCloud: true,
+ isForceV3Project: true,
+ }),
+ ).toBe(false);
+ });
+});
diff --git a/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts b/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts
index 1a40f60845..980e82b211 100644
--- a/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts
+++ b/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts
@@ -10,6 +10,7 @@ vi.mock("@/src/server/auth", () => ({
const sharedServerMock = vi.hoisted(() => ({
queryClickhouse: vi.fn(),
+ isForceV3ExperienceProject: vi.fn(() => false),
logger: {
warn: vi.fn(),
},
@@ -823,6 +824,7 @@ describe("v4TransitionRouter", () => {
mixpanel: false,
blobStorage: false,
},
+ forceV3Experience: false,
},
{
projectId: secondProjectId,
@@ -833,6 +835,7 @@ describe("v4TransitionRouter", () => {
mixpanel: true,
blobStorage: false,
},
+ forceV3Experience: false,
},
],
});
@@ -1005,6 +1008,7 @@ describe("v4TransitionRouter", () => {
mixpanel: false,
blobStorage: false,
},
+ forceV3Experience: false,
},
],
});
diff --git a/web/src/components/layouts/app-layout/variants/AuthenticatedLayout.tsx b/web/src/components/layouts/app-layout/variants/AuthenticatedLayout.tsx
index 4d04ba1c77..af0717d25e 100644
--- a/web/src/components/layouts/app-layout/variants/AuthenticatedLayout.tsx
+++ b/web/src/components/layouts/app-layout/variants/AuthenticatedLayout.tsx
@@ -316,7 +316,7 @@ function ConnectedAppSidebar({
}) {
const { isMobile } = useSidebar();
const uiCustomization = useUiCustomization();
- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();
+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(routerProjectId);
const plan = usePlan();
const capture = usePostHogClientCapture();
const session = useSession();
diff --git a/web/src/features/evals/components/eval-version-callout.tsx b/web/src/features/evals/components/eval-version-callout.tsx
index f1c3cd1a94..f8cc1a452c 100644
--- a/web/src/features/evals/components/eval-version-callout.tsx
+++ b/web/src/features/evals/components/eval-version-callout.tsx
@@ -83,6 +83,12 @@ const getCalloutContent = (
// For dataset target (legacy dataset run methods)
if (isDatasetTarget(targetObject)) {
+ // Forced-v3 projects keep trace evaluators as their intended experience β€”
+ // no upgrade nag.
+ if (evalCapabilities.forceV3Experience) {
+ return hidden;
+ }
+
return {
visible: true,
title: "Legacy low-level SDK methods",
@@ -108,6 +114,12 @@ const getCalloutContent = (
// For trace target
if (isTraceTarget(targetObject)) {
+ // Forced-v3 projects keep trace evaluators as their intended experience β€”
+ // no upgrade nag.
+ if (evalCapabilities.forceV3Experience) {
+ return hidden;
+ }
+
return {
visible: true,
title: "Consider upgrading to observation evaluators",
diff --git a/web/src/features/evals/components/evaluator-table.tsx b/web/src/features/evals/components/evaluator-table.tsx
index 5b101271fb..60fc1d920a 100644
--- a/web/src/features/evals/components/evaluator-table.tsx
+++ b/web/src/features/evals/components/evaluator-table.tsx
@@ -74,7 +74,7 @@ function DeprecatedChipCell() {
export default function EvaluatorTable({ projectId }: { projectId: string }) {
const router = useRouter();
const capture = usePostHogClientCapture();
- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();
+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(projectId);
const { setDetailPageList } = useDetailPageLists();
const [paginationState, setPaginationState] = usePaginationState(0, 50, {
page: "pageIndex",
diff --git a/web/src/features/evals/components/inner-evaluator-form.tsx b/web/src/features/evals/components/inner-evaluator-form.tsx
index 3082a1db69..7aa671c89b 100644
--- a/web/src/features/evals/components/inner-evaluator-form.tsx
+++ b/web/src/features/evals/components/inner-evaluator-form.tsx
@@ -94,6 +94,7 @@ import {
isExperimentTarget,
isLegacyEvalTarget,
isTraceTarget,
+ shouldShowLegacyTracePreview,
} from "@/src/features/evals/utils/typeHelpers";
import {
useUserFacingTarget,
@@ -1252,7 +1253,12 @@ export const InnerEvaluatorForm = (props: {
{/* Preview based on target type */}
{previewTableVisible && (
<>
- {isTraceTarget(form.watch("target")) && (
+ {/* The traces preview reads the legacy traces table, which
+ is not the v4 user's experience β€” never show it there. */}
+ {shouldShowLegacyTracePreview(
+ form.watch("target"),
+ isBetaEnabled,
+ ) && (
<TracesPreview
projectId={props.projectId}
filterState={watchedFilter}
diff --git a/web/src/features/evals/components/variable-mapping-card.tsx b/web/src/features/evals/components/variable-mapping-card.tsx
index 439fb473e4..af49d86a59 100644
--- a/web/src/features/evals/components/variable-mapping-card.tsx
+++ b/web/src/features/evals/components/variable-mapping-card.tsx
@@ -32,8 +32,8 @@ import {
isEventTarget,
isExperimentTarget,
isLegacyEvalTarget,
- isTraceTarget,
isTraceOrDatasetObject,
+ shouldShowLegacyTracePreview,
} from "@/src/features/evals/utils/typeHelpers";
import {
FormControl,
@@ -98,8 +98,10 @@ export const VariableMappingCard = ({
typeof router.query.peek === "string" ? router.query.peek : undefined;
const isPeekView = Boolean(peekId);
const target = form.watch("target");
+ // The trace preview reads the legacy traces table, which is not the v4
+ // user's experience β€” never offer it there.
const shouldShowPreviewForTarget =
- isTraceTarget(target) ||
+ shouldShowLegacyTracePreview(target, isBetaEnabled) ||
isEventTarget(target) ||
(isExperimentTarget(target) && isBetaEnabled);
@@ -241,12 +243,13 @@ export const VariableMappingCard = ({
)}
</div>
</div>
- {isTraceTarget(form.watch("target")) && !disabled && (
- <FormDescription>
- Preview of the evaluation prompt with the variables replaced with the
- first matched trace data subject to the filters.
- </FormDescription>
- )}
+ {shouldShowLegacyTracePreview(form.watch("target"), isBetaEnabled) &&
+ !disabled && (
+ <FormDescription>
+ Preview of the evaluation prompt with the variables replaced with
+ the first matched trace data subject to the filters.
+ </FormDescription>
+ )}
<div className="flex max-w-full flex-col gap-4">
<FormField
control={form.control}
@@ -259,7 +262,10 @@ export const VariableMappingCard = ({
!shouldWrapVariables && "lg:flex-row",
)}
>
- {showPreview ? (
+ {/* Derive eligibility at render time: showPreview is state set
+ by an effect and must never override target eligibility
+ (e.g. trace targets on v4 have no preview data source). */}
+ {showPreview && shouldShowPreviewControls ? (
previewData ? (
<EvaluationPromptPreview
projectId={projectId}
diff --git a/web/src/features/evals/hooks/useEvalCapabilities.ts b/web/src/features/evals/hooks/useEvalCapabilities.ts
index 7a0ff2697c..8c1fb288e2 100644
--- a/web/src/features/evals/hooks/useEvalCapabilities.ts
+++ b/web/src/features/evals/hooks/useEvalCapabilities.ts
@@ -3,6 +3,8 @@ import { api } from "@/src/utils/api";
import { useLangfuseCloudRegion } from "@/src/features/organizations/hooks";
import { useV4Beta } from "@/src/features/events/hooks/useV4Beta";
import { useIsCodeEvalEnabled } from "@/src/features/evals/hooks/useIsCodeEvalEnabled";
+import { useForceV3Experience } from "@/src/features/v4-migration/useForceV3Experience";
+import { isNewLegacyEvalAllowed } from "@/src/features/evals/utils/legacyEvalGate";
export interface EvalCapabilities {
isNewCompatible: boolean;
@@ -10,6 +12,7 @@ export interface EvalCapabilities {
allowLegacy: boolean;
isLoading: boolean;
hasLegacyEvals: boolean;
+ forceV3Experience: boolean;
}
/**
@@ -35,7 +38,7 @@ export function useEvalCapabilities(
// Query SDK version info from events table (only when v4 beta is enabled)
const sdkVersionInfo = api.events.getSdkVersionInfo.useQuery(
{ projectId },
- { enabled: isBetaEnabled },
+ { enabled: isBetaEnabled && Boolean(projectId) },
);
// Determine OTEL status from SDK version info
@@ -44,9 +47,7 @@ export function useEvalCapabilities(
// Get eval counts including legacy eval count
const evalCounts = api.evals.counts.useQuery(
{ projectId },
- {
- enabled: !!projectId,
- },
+ { enabled: Boolean(projectId) },
);
const hasLegacyEvals = (evalCounts.data?.legacyConfigCount ?? 0) > 0;
@@ -56,18 +57,15 @@ export function useEvalCapabilities(
const { isLangfuseCloud } = useLangfuseCloudRegion();
const v4WriteMode = session?.environment?.v4WriteMode;
- // Whether a *new* config may use the legacy experience:
- // - events_only: legacy tables are no longer written β†’ no new legacy evals.
- // - dual: self-hosted deployments always allow legacy; on Cloud, no new
- // legacy evals β€” existing legacy evaluators stay visible in read-only mode,
- // but cannot be newly set up.
- // - legacy: legacy is the only experience.
- const modeAllowsNewLegacy =
- v4WriteMode === "events_only"
- ? false
- : v4WriteMode === "dual"
- ? !isLangfuseCloud
- : v4WriteMode === "legacy"; // legacy β†’ true; undefined (loading) β†’ false
+ // Projects forced onto v3 keep legacy evals while legacy tables are written.
+ const forceV3Experience = useForceV3Experience(projectId);
+
+ // Whether a *new* config may use the legacy experience.
+ const modeAllowsNewLegacy = isNewLegacyEvalAllowed({
+ v4WriteMode,
+ isLangfuseCloud,
+ isForceV3Project: forceV3Experience,
+ });
return {
isNewCompatible: isOtel,
@@ -80,5 +78,6 @@ export function useEvalCapabilities(
isLoading:
evalCounts.isLoading || isSessionLoading || sdkVersionInfo.isLoading,
hasLegacyEvals,
+ forceV3Experience,
};
}
diff --git a/web/src/features/evals/hooks/useEvalConfigMappingData.ts b/web/src/features/evals/hooks/useEvalConfigMappingData.ts
index e4fd0a4468..ecc76340cc 100644
--- a/web/src/features/evals/hooks/useEvalConfigMappingData.ts
+++ b/web/src/features/evals/hooks/useEvalConfigMappingData.ts
@@ -8,6 +8,7 @@ import {
} from "@/src/features/evals/hooks/usePreviewData";
import { useEffect, useRef } from "react";
import { useV4Beta } from "@/src/features/events/hooks/useV4Beta";
+import { isTraceTargetOnV4 } from "@/src/features/evals/utils/typeHelpers";
import {
type EvalPreviewPointer,
getEvalPreviewPointerFromUrlQuery,
@@ -42,9 +43,13 @@ export function useEvalConfigMappingData(
const previewPointer =
selectedPreviewPointer ?? urlPreviewPointer ?? firstPreviewPointer;
+ // The trace preview reads the legacy traces table, which is not the v4
+ // user's experience β€” never fetch or expect preview data there.
+ const traceTargetOnV4 = isTraceTargetOnV4(targetValue, isBetaEnabled);
+
const { previewData, isLoading } = usePreviewData({
projectId,
- enabled: !disabled && Boolean(previewPointer),
+ enabled: !disabled && !traceTargetOnV4 && Boolean(previewPointer),
target: targetValue,
traceId: previewPointer?.traceId,
observationId: previewPointer?.observationId,
diff --git a/web/src/features/evals/pages/remap-evaluator.tsx b/web/src/features/evals/pages/remap-evaluator.tsx
index 88b7400c3f..003e75c0fe 100644
--- a/web/src/features/evals/pages/remap-evaluator.tsx
+++ b/web/src/features/evals/pages/remap-evaluator.tsx
@@ -47,7 +47,7 @@ export default function RemapEvaluatorPage() {
const router = useRouter();
const projectId = router.query.projectId as string;
const evalConfigId = router.query.evaluator as string;
- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();
+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(projectId);
const capture = usePostHogClientCapture();
const { organization } = useQueryProject();
const canUseAssistant = useCanUseInAppAgent();
diff --git a/web/src/features/evals/server/legacyEvalGate.ts b/web/src/features/evals/server/legacyEvalGate.ts
new file mode 100644
index 0000000000..647fb90711
--- /dev/null
+++ b/web/src/features/evals/server/legacyEvalGate.ts
@@ -0,0 +1,31 @@
+import { env } from "@/src/env.mjs";
+import { InvalidRequestError } from "@langfuse/shared";
+import { isForceV3ExperienceProject } from "@langfuse/shared/src/server";
+import { isLegacyEvalTarget } from "@/src/features/evals/utils/typeHelpers";
+import { isNewLegacyEvalAllowed } from "@/src/features/evals/utils/legacyEvalGate";
+
+/**
+ * Server-side guard mirroring the UI capability hook: reject creating a *new*
+ * legacy-target (trace/dataset) evaluator on deployments where the legacy
+ * experience is disabled. Forced-v3 projects are exempt unless events_only is
+ * set. Non-legacy targets and updates to existing evaluators are unaffected.
+ */
+export function assertCanCreateLegacyEvalJob(params: {
+ projectId: string;
+ target: string;
+}): void {
+ const { projectId, target } = params;
+ if (!isLegacyEvalTarget(target)) return;
+
+ const allowed = isNewLegacyEvalAllowed({
+ v4WriteMode: env.LANGFUSE_MIGRATION_V4_WRITE_MODE,
+ isLangfuseCloud: Boolean(env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION),
+ isForceV3Project: isForceV3ExperienceProject(projectId),
+ });
+
+ if (!allowed) {
+ throw new InvalidRequestError(
+ "Trace- and dataset-level evaluators are no longer available. Create an observation- or experiment-level evaluator instead.",
+ );
+ }
+}
diff --git a/web/src/features/evals/server/router.ts b/web/src/features/evals/server/router.ts
index 7fa3f5797b..ad05bf96b0 100644
--- a/web/src/features/evals/server/router.ts
+++ b/web/src/features/evals/server/router.ts
@@ -97,6 +97,7 @@ import {
prepareVariableMappingForEvaluatorUpgrade,
} from "@/src/features/evals/server/evaluatorUpgrade";
import { deleteJobConfigurationWithExecutions } from "@/src/features/evals/server/evaluatorRepository";
+import { assertCanCreateLegacyEvalJob } from "@/src/features/evals/server/legacyEvalGate";
export { CreateEvalTemplateInputSchema } from "@/src/features/evals/server/evalTemplateCreation";
// Filter columns that used to be backed by the Postgres `traces` and
@@ -1004,6 +1005,11 @@ export const evalRouter = createTRPCRouter({
scope: "evalJob:CUD",
});
+ assertCanCreateLegacyEvalJob({
+ projectId: input.projectId,
+ target: input.target,
+ });
+
const evalTemplate = await ctx.prisma.evalTemplate.findFirst({
where: {
id: input.evalTemplateId,
diff --git a/web/src/features/evals/utils/legacyEvalGate.ts b/web/src/features/evals/utils/legacyEvalGate.ts
new file mode 100644
index 0000000000..c965d8c5c7
--- /dev/null
+++ b/web/src/features/evals/utils/legacyEvalGate.ts
@@ -0,0 +1,23 @@
+/**
+ * Pure decision shared by the client capability hook (`useEvalCapabilities`)
+ * and the server create-gate (`assertCanCreateLegacyEvalJob`): may a *new*
+ * evaluator use the legacy (trace/dataset) experience?
+ *
+ * - events_only: legacy tables are no longer written β†’ no new legacy evals.
+ * - dual: self-hosted deployments always allow legacy; on Cloud, no new legacy.
+ * - legacy: legacy is the only experience.
+ * - forced-v3 projects keep the legacy experience unless events_only is set.
+ * - undefined write mode (session still loading client-side) β†’ not allowed,
+ * which keeps legacy options hidden until the mode is known.
+ */
+export function isNewLegacyEvalAllowed(params: {
+ v4WriteMode: "legacy" | "dual" | "events_only" | undefined;
+ isLangfuseCloud: boolean;
+ isForceV3Project: boolean;
+}): boolean {
+ const { v4WriteMode, isLangfuseCloud, isForceV3Project } = params;
+ if (v4WriteMode === "events_only") return false;
+ if (isForceV3Project) return true;
+ if (v4WriteMode === "dual") return !isLangfuseCloud;
+ return v4WriteMode === "legacy";
+}
diff --git a/web/src/features/evals/utils/typeHelpers.ts b/web/src/features/evals/utils/typeHelpers.ts
index 2608987b69..eb394d91bc 100644
--- a/web/src/features/evals/utils/typeHelpers.ts
+++ b/web/src/features/evals/utils/typeHelpers.ts
@@ -54,6 +54,18 @@ export const isTraceTarget = (targetObject: string): boolean => {
return targetObject === EvalTargetObject.TRACE;
};
+export const isTraceTargetOnV4 = (
+ targetObject: string,
+ isBetaEnabled: boolean,
+): boolean => isTraceTarget(targetObject) && isBetaEnabled;
+
+export const shouldShowLegacyTracePreview = (
+ targetObject: string,
+ isBetaEnabled: boolean,
+): boolean =>
+ isTraceTarget(targetObject) &&
+ !isTraceTargetOnV4(targetObject, isBetaEnabled);
+
export const isEventTarget = (targetObject: string): boolean => {
return targetObject === EvalTargetObject.EVENT;
};
diff --git a/web/src/features/events/components/V4SidebarToggle.tsx b/web/src/features/events/components/V4SidebarToggle.tsx
index 8724d363bc..6eca7de72e 100644
--- a/web/src/features/events/components/V4SidebarToggle.tsx
+++ b/web/src/features/events/components/V4SidebarToggle.tsx
@@ -10,6 +10,7 @@ import { useV4Beta } from "@/src/features/events/hooks/useV4Beta";
import { V4IntroDialog } from "@/src/features/events/components/V4IntroDialog";
import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";
import { useV4UpgradeUiEnabled } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";
+import { useQueryProject } from "@/src/features/projects/hooks";
import { ZapIcon } from "lucide-react";
import { useId } from "react";
import { useRouter } from "next/router";
@@ -127,7 +128,8 @@ export function V4SidebarToggle() {
confirmIntroDialog,
dismissIntroDialog,
} = useV4PreviewToggle("sidebar");
- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();
+ const { project } = useQueryProject();
+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(project?.id);
// v4-upgrade users get this toggle inside the migration panel instead.
if (!canToggleV4 || v4UpgradeUiEnabled) {
diff --git a/web/src/features/support-chat/SupportFormSection.tsx b/web/src/features/support-chat/SupportFormSection.tsx
index 9f0588ff84..0b06a46944 100644
--- a/web/src/features/support-chat/SupportFormSection.tsx
+++ b/web/src/features/support-chat/SupportFormSection.tsx
@@ -198,7 +198,7 @@ export function SupportFormSection({
const [sev1ConfirmOpen, setSev1ConfirmOpen] = useState(false);
const { initialTopic } = useSupportDrawer();
- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();
+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(project?.id);
const productFeatureTopics = TopicGroups["Product Features"].filter(
(topic) => topic !== "V4 Migration" || v4UpgradeUiEnabled,
);
diff --git a/web/src/features/v4-migration/V4MigrationBanner.clienttest.tsx b/web/src/features/v4-migration/V4MigrationBanner.clienttest.tsx
index 315f63d115..718ed74893 100644
--- a/web/src/features/v4-migration/V4MigrationBanner.clienttest.tsx
+++ b/web/src/features/v4-migration/V4MigrationBanner.clienttest.tsx
@@ -61,6 +61,7 @@ const status = (
experiments: { status: "loaded", result: "not_required" },
apis: { status: "loaded", count: 0 },
exports: { status: "loaded", count: 0 },
+ forceV3Experience: false,
...overrides,
});
diff --git a/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsx b/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsx
index 5cb6abd5ef..23bf91af93 100644
--- a/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsx
+++ b/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsx
@@ -1,4 +1,4 @@
-import { render, screen } from "@testing-library/react";
+import { fireEvent, render, screen } from "@testing-library/react";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { V4MigrationDelayBadge } from "./V4MigrationDelayBadge";
@@ -58,11 +58,22 @@ const mocks = vi.hoisted(() => ({
delayedOtelIngestionCount: 0,
} as V4MigrationSdkState,
v4UpgradeUiEnabled: true,
+ forceV3: false,
+ isBetaEnabled: false,
openMigrationPanel: vi.fn(),
}));
vi.mock("@/src/features/v4-migration/useV4UpgradeUiEnabled", () => ({
useV4UpgradeUiEnabled: () => mocks.v4UpgradeUiEnabled,
+ useV4UpgradeUiFlag: () => mocks.v4UpgradeUiEnabled,
+}));
+
+vi.mock("@/src/features/v4-migration/useForceV3Experience", () => ({
+ useForceV3Experience: () => mocks.forceV3,
+}));
+
+vi.mock("@/src/features/events/hooks/useV4Beta", () => ({
+ useV4Beta: () => ({ isBetaEnabled: mocks.isBetaEnabled }),
}));
vi.mock("@/src/features/posthog-analytics/usePostHogClientCapture", () => ({
@@ -120,6 +131,8 @@ describe("V4MigrationDelayBadge", () => {
beforeEach(() => {
vi.clearAllMocks();
mocks.v4UpgradeUiEnabled = true;
+ mocks.forceV3 = false;
+ mocks.isBetaEnabled = false;
setSdk("latest", [makeSdkUsageSeries({})]);
});
@@ -192,4 +205,34 @@ describe("V4MigrationDelayBadge", () => {
render(<V4MigrationDelayBadge />);
expect(screen.queryByText("New data in ~15 min")).not.toBeInTheDocument();
});
+
+ it("stays hidden for forced-v3 projects while they view v3", () => {
+ // On v3 views the legacy tables are real-time β€” no delay to announce.
+ mocks.forceV3 = true;
+ mocks.isBetaEnabled = false;
+ setSdk("legacy", [outdatedSdkSeries()]);
+ render(<V4MigrationDelayBadge />);
+ expect(screen.queryByText("New data in ~15 min")).not.toBeInTheDocument();
+ });
+
+ it("opens the partner FAQ instead of the panel for forced-v3 projects on v4", () => {
+ mocks.forceV3 = true;
+ mocks.isBetaEnabled = true;
+ setSdk("legacy", [outdatedSdkSeries()]);
+ const windowOpen = vi.spyOn(window, "open").mockImplementation(() => null);
+
+ render(<V4MigrationDelayBadge />);
+ expect(
+ screen.getAllByText(/Learn more in the docs/).length,
+ ).toBeGreaterThan(0);
+
+ fireEvent.click(screen.getAllByText("New data in ~15 min")[0]);
+ expect(windowOpen).toHaveBeenCalledWith(
+ expect.stringContaining("langfuse.com"),
+ "_blank",
+ "noopener,noreferrer",
+ );
+ expect(mocks.openMigrationPanel).not.toHaveBeenCalled();
+ windowOpen.mockRestore();
+ });
});
diff --git a/web/src/features/v4-migration/V4MigrationDelayBadge.tsx b/web/src/features/v4-migration/V4MigrationDelayBadge.tsx
index 5928879467..e86eac035c 100644
--- a/web/src/features/v4-migration/V4MigrationDelayBadge.tsx
+++ b/web/src/features/v4-migration/V4MigrationDelayBadge.tsx
@@ -1,5 +1,11 @@
import { useState } from "react";
-import { useV4UpgradeUiEnabled } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";
+import { useRouter } from "next/router";
+import {
+ useV4UpgradeUiEnabled,
+ useV4UpgradeUiFlag,
+} from "@/src/features/v4-migration/useV4UpgradeUiEnabled";
+import { useForceV3Experience } from "@/src/features/v4-migration/useForceV3Experience";
+import { PARTNER_INTEGRATION_FAQ_URL } from "@/src/features/v4-migration/partnerIntegrationDocs";
import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";
import { useQueryProject } from "@/src/features/projects/hooks";
import { useOpenV4MigrationPanel } from "@/src/features/v4-migration/hooks/useOpenV4MigrationPanel";
@@ -15,17 +21,23 @@ import {
} from "@/src/features/v4-migration/sdkVersionStatus";
import { EvaluatorMigrationDialog } from "@/src/features/v4-migration/EvaluatorMigrationDialog";
import { buildDeprecatedEvaluatorsUrl } from "@/src/features/v4-migration/evaluatorMigrationUrls";
-import { useRouter } from "next/router";
+import { useV4Beta } from "@/src/features/events/hooks/useV4Beta";
export function V4MigrationDelayBadge() {
- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();
+ const v4UpgradeUiFlagEnabled = useV4UpgradeUiFlag();
const openMigrationPanel = useOpenV4MigrationPanel();
const { project, organization } = useQueryProject();
+ const forceV3 = useForceV3Experience(project?.id);
+ const { isBetaEnabled } = useV4Beta();
const capture = usePostHogClientCapture();
+
+ // Forced-v3 projects still see the data-delay badge, but it points at the
+ // partner FAQ instead of the migration panel
+ const enabled = v4UpgradeUiFlagEnabled && (!forceV3 || isBetaEnabled);
const sdk = useProjectV4SdkData({
projectId: project?.id,
orgId: organization?.id,
- enabled: v4UpgradeUiEnabled && Boolean(project),
+ enabled: enabled && Boolean(project),
});
// Every delayed ingestion path shows the pill, matching the migration
@@ -45,11 +57,16 @@ export function V4MigrationDelayBadge() {
customActionable,
].filter(Boolean).length;
- if (!v4UpgradeUiEnabled || !project || actionablePaths === 0) {
+ if (!enabled || !project || actionablePaths === 0) {
return null;
}
const handleClick = () => {
+ if (forceV3) {
+ capture("v4_migration:delay_badge_clicked", { action: "docs" });
+ window.open(PARTNER_INTEGRATION_FAQ_URL, "_blank", "noopener,noreferrer");
+ return;
+ }
capture("v4_migration:delay_badge_clicked");
openMigrationPanel({ id: project.id, name: project.name }, "delay_badge");
};
@@ -69,7 +86,7 @@ export function V4MigrationDelayBadge() {
<V4MigrationBadgeContent
onClick={handleClick}
title="New data in ~15 min"
- description={description}
+ description={forceV3 ? "Learn more in the docs" : description}
/>
);
}
@@ -77,8 +94,8 @@ export function V4MigrationDelayBadge() {
/** Shared gating for the eval "Action required" badges: v4 upgrade UI flag,
* project context, and a loaded, non-zero deprecated-eval count. */
function useEvalUpdateRequiredBadgeState() {
- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();
const { project, organization } = useQueryProject();
+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(project?.id);
const enabled = v4UpgradeUiEnabled && Boolean(project);
const evalState = useProjectV4EvalData({
projectId: project?.id,
diff --git a/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsx b/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsx
index c88fdbbe86..36a10754d4 100644
--- a/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsx
+++ b/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsx
@@ -61,6 +61,7 @@ const migrationStatus = (
experiments: { status: "loaded", result: "not_required" },
apis: { status: "loaded", count: 0 },
exports: { status: "loaded", count: 0 },
+ forceV3Experience: false,
...overrides,
});
diff --git a/web/src/features/v4-migration/V4MigrationModal.tsx b/web/src/features/v4-migration/V4MigrationModal.tsx
index fbf8f32252..c96a756670 100644
--- a/web/src/features/v4-migration/V4MigrationModal.tsx
+++ b/web/src/features/v4-migration/V4MigrationModal.tsx
@@ -17,7 +17,7 @@ import { api } from "@/src/utils/api";
// use deprecated features (currently Evals) and opens on arrival.
export function V4MigrationModal() {
const { project } = useQueryProject();
- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();
+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(project?.id);
const traceLevelEvalSummary = api.v4Transition.traceLevelEvalSummary.useQuery(
{ projectId: project?.id ?? "" },
{
diff --git a/web/src/features/v4-migration/V4MigrationNavItem.tsx b/web/src/features/v4-migration/V4MigrationNavItem.tsx
index 4c9cef27cd..7af397b721 100644
--- a/web/src/features/v4-migration/V4MigrationNavItem.tsx
+++ b/web/src/features/v4-migration/V4MigrationNavItem.tsx
@@ -8,10 +8,10 @@ import { getProjectMigrationReadiness } from "@/src/features/v4-migration/migrat
import { useOpenV4MigrationPanel } from "@/src/features/v4-migration/hooks/useOpenV4MigrationPanel";
export function V4MigrationNavItem() {
- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();
+ const { project, organization } = useQueryProject();
+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(project?.id);
const openMigrationPanel = useOpenV4MigrationPanel();
const { isMobile, setOpenMobile: setOpenMobileSidebar } = useSidebar();
- const { project, organization } = useQueryProject();
const capture = usePostHogClientCapture();
const migrationData = useProjectV4MigrationData({
projectId: project?.id,
@@ -28,6 +28,7 @@ export function V4MigrationNavItem() {
experiments: migrationData.experiments,
apis: migrationData.apis,
exports: migrationData.exports,
+ forceV3Experience: migrationData.forceV3Experience,
});
if (readiness === "ready") {
return null;
diff --git a/web/src/features/v4-migration/V4MigrationPanelProvider.clienttest.tsx b/web/src/features/v4-migration/V4MigrationPanelProvider.clienttest.tsx
index 5e02443d15..67aa893c90 100644
--- a/web/src/features/v4-migration/V4MigrationPanelProvider.clienttest.tsx
+++ b/web/src/features/v4-migration/V4MigrationPanelProvider.clienttest.tsx
@@ -15,6 +15,10 @@ vi.mock("./useV4UpgradeUiEnabled", () => ({
useV4UpgradeUiEnabled: () => flagState.enabled,
}));
+vi.mock("@/src/features/projects/hooks", () => ({
+ useQueryProject: () => ({ project: null, organization: null }),
+}));
+
vi.mock("@/src/features/posthog-analytics/usePostHogClientCapture", () => ({
usePostHogClientCapture: () => captureMock,
}));
diff --git a/web/src/features/v4-migration/V4MigrationPanelProvider.tsx b/web/src/features/v4-migration/V4MigrationPanelProvider.tsx
index 44397ce702..1ca0fc9a15 100644
--- a/web/src/features/v4-migration/V4MigrationPanelProvider.tsx
+++ b/web/src/features/v4-migration/V4MigrationPanelProvider.tsx
@@ -6,6 +6,7 @@ import {
} from "react";
import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";
import { useV4UpgradeUiEnabled } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";
+import { useQueryProject } from "@/src/features/projects/hooks";
export type V4MigrationTargetProject = { id: string; name: string };
@@ -39,7 +40,8 @@ export function V4MigrationPanelProvider({
children,
defaultOpen = false,
}: V4MigrationPanelProviderProps) {
- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();
+ const { project: routeProject } = useQueryProject();
+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(routeProject?.id);
const capture = usePostHogClientCapture();
const [requestedOpen, setRequestedOpen] = useState(defaultOpen);
const [targetProject, setTargetProject] =
diff --git a/web/src/features/v4-migration/V4MigrationProjectChip.tsx b/web/src/features/v4-migration/V4MigrationProjectChip.tsx
index b5bf4279a3..e049e1aeea 100644
--- a/web/src/features/v4-migration/V4MigrationProjectChip.tsx
+++ b/web/src/features/v4-migration/V4MigrationProjectChip.tsx
@@ -5,6 +5,7 @@ import {
type ProjectMigrationStatus,
} from "@/src/features/v4-migration/migrationData";
import { useOpenV4MigrationPanel } from "@/src/features/v4-migration/hooks/useOpenV4MigrationPanel";
+import { PARTNER_INTEGRATION_FAQ_URL } from "@/src/features/v4-migration/partnerIntegrationDocs";
export function V4MigrationProjectChip({
project,
@@ -17,6 +18,27 @@ export function V4MigrationProjectChip({
const capture = usePostHogClientCapture();
const readiness = status ? getProjectMigrationReadiness(status) : "checking";
+
+ // Forced-v3 projects show no migration action β€” the upgrade is handled by
+ // their integration partner. Point them at the FAQ instead.
+ if (readiness === "partner-managed") {
+ return (
+ <a
+ href={PARTNER_INTEGRATION_FAQ_URL}
+ target="_blank"
+ rel="noopener noreferrer"
+ onClick={(event) => {
+ // Card is wrapped in a full-bleed <Link>; keep the docs link isolated.
+ event.stopPropagation();
+ }}
+ className="text-muted-foreground ring-border hover:bg-muted/50 relative inline-flex shrink-0 items-center gap-1.5 rounded-full px-2 py-0.5 text-xs whitespace-nowrap ring"
+ title="Upgrade is handled by your integration partner. Click on badge to learn more."
+ >
+ Update to v4 managed by integration partner
+ </a>
+ );
+ }
+
if (readiness === "ready") {
return null;
}
diff --git a/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx b/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx
index 2d8160d539..95b3caca9b 100644
--- a/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx
+++ b/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx
@@ -90,6 +90,7 @@ vi.mock("@/src/features/v4-migration/hooks/useV4MigrationData", () => ({
experiments: { status: "loaded", result: "not_required" },
apis: { status: "loaded", count: 0 },
exports: { status: "loaded", count: 0 },
+ forceV3Experience: false,
},
],
]),
diff --git a/web/src/features/v4-migration/V4MigrationStatusPage.tsx b/web/src/features/v4-migration/V4MigrationStatusPage.tsx
index c58b15cc1d..fc2d833c4c 100644
--- a/web/src/features/v4-migration/V4MigrationStatusPage.tsx
+++ b/web/src/features/v4-migration/V4MigrationStatusPage.tsx
@@ -34,6 +34,7 @@ import {
type ProjectMigrationReadiness,
type ProjectMigrationStatus,
} from "@/src/features/v4-migration/migrationData";
+import { PARTNER_INTEGRATION_FAQ_URL } from "@/src/features/v4-migration/partnerIntegrationDocs";
const V4_DOCS_URL = "https://langfuse.com/docs/v4";
const SDK_UPGRADE_URL =
@@ -86,6 +87,23 @@ function MigrationActionCell({ state }: { state: MigrationActionState }) {
}
function StatusPill({ readiness }: { readiness: ProjectMigrationReadiness }) {
+ // Forced-v3 projects are managed by their integration partner β€” link the pill
+ // straight to the FAQ instead of showing a migration action state.
+ if (readiness === "partner-managed") {
+ return (
+ <a
+ href={PARTNER_INTEGRATION_FAQ_URL}
+ target="_blank"
+ rel="noopener noreferrer"
+ onClick={(event) => event.stopPropagation()}
+ className="bg-muted text-muted-foreground inline-flex w-fit shrink-0 items-center rounded-full px-2 py-0.5 text-xs font-bold whitespace-nowrap hover:underline"
+ title="Upgrade is handled by your integration partner"
+ >
+ Integration partner
+ </a>
+ );
+ }
+
const label =
readiness === "ready"
? "Migrated"
@@ -175,8 +193,15 @@ function OrgStatusSection({
openMigrationPanel({ id: row.id, name: row.name }, "status_page_row");
};
- const handleRowClick = (row: { id: string; name: string }) => {
- openProjectMigration(row);
+ const handleRowClick = (row: {
+ id: string;
+ name: string;
+ status?: ProjectMigrationStatus;
+ }) => {
+ // Forced-v3 projects have no migration panel β€” just navigate to the project.
+ if (!row.status?.forceV3Experience) {
+ openProjectMigration(row);
+ }
router.push(`/project/${row.id}/traces`);
};
@@ -225,6 +250,7 @@ function OrgStatusSection({
checking: 1,
"action-needed": 2,
ready: 3,
+ "partner-managed": 4,
}[getProjectMigrationReadiness(row.status)]
: 0;
case "sdk":
@@ -352,7 +378,10 @@ function OrgStatusSection({
title={row.name}
onClick={(event) => {
event.stopPropagation();
- openProjectMigration(row);
+ // Forced-v3 projects have no migration panel.
+ if (!row.status?.forceV3Experience) {
+ openProjectMigration(row);
+ }
}}
>
{row.name}
diff --git a/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts b/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts
index f401e31be8..cefd0dba44 100644
--- a/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts
+++ b/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts
@@ -142,6 +142,7 @@ describe("account v4 migration data", () => {
},
apis: { status: "loaded", count: 2 },
exports: { status: "loaded", count: 1 },
+ forceV3Experience: false,
});
expect(mocks.summaryByProject).toHaveBeenCalledWith(
{ orgId: "org-1" },
@@ -156,4 +157,29 @@ describe("account v4 migration data", () => {
expect.objectContaining({ enabled: true }),
);
});
+
+ it("marks projects forced onto the v3 experience as partner-managed", () => {
+ const [integrationResultSet] = mocks.queryResultSets as [
+ [{ data: { projects: Record<string, unknown>[] } }],
+ ...unknown[][],
+ ];
+ integrationResultSet[0].data.projects[0].forceV3Experience = true;
+
+ const { result } = renderHook(() =>
+ useAccountV4MigrationData({
+ organizations: [
+ {
+ id: "org-1",
+ name: "Organization",
+ projects: [{ id: "project-1", name: "Project" }],
+ },
+ ],
+ enabled: true,
+ }),
+ );
+
+ expect(result.current.get("project-1")).toMatchObject({
+ forceV3Experience: true,
+ });
+ });
});
diff --git a/web/src/features/v4-migration/hooks/useV4MigrationData.ts b/web/src/features/v4-migration/hooks/useV4MigrationData.ts
index 9e37c73609..4df5b195ba 100644
--- a/web/src/features/v4-migration/hooks/useV4MigrationData.ts
+++ b/web/src/features/v4-migration/hooks/useV4MigrationData.ts
@@ -11,6 +11,7 @@ import {
type ProjectMigrationStatus,
} from "@/src/features/v4-migration/migrationData";
import { getV4MigrationSdkState } from "@/src/features/v4-migration/sdkVersionStatus";
+import { useForceV3Experience } from "@/src/features/v4-migration/useForceV3Experience";
const QUERY_STALE_TIME_MS = 5 * 60 * 1000;
@@ -85,7 +86,6 @@ export function useAccountV4MigrationData(params: {
),
),
);
-
const statusByProjectId = new Map<string, ProjectMigrationStatus>();
organizations.forEach((organization, organizationIndex) => {
@@ -127,6 +127,13 @@ export function useAccountV4MigrationData(params: {
?.legacyIntegrationCount ?? 0
);
}),
+ // Forced-v3 projects still appear in the aggregation, marked as
+ // partner-managed so surfaces can show "upgrade handled by your
+ // integration partner" instead of a user-facing migration action.
+ forceV3Experience:
+ integrationQuery?.data?.projects.find(
+ (row) => row.projectId === project.id,
+ )?.forceV3Experience === true,
});
});
});
@@ -194,6 +201,7 @@ export function useProjectV4MigrationData(params: {
const { projectId, orgId, enabled } = params;
const queryEnabled = enabled && Boolean(projectId);
const [detectionRange] = useState(createV4MigrationDetectionRange);
+ const forceV3Experience = useForceV3Experience(projectId);
const { sdkQuery, summary: sdkSummary } = useProjectV4SdkSummary({
projectId,
orgId,
@@ -248,6 +256,7 @@ export function useProjectV4MigrationData(params: {
integrationQuery,
(data) => data.legacyIntegrationCount,
),
+ forceV3Experience,
apiUsage,
legacyIntegrations,
};
diff --git a/web/src/features/v4-migration/migrationData.clienttest.ts b/web/src/features/v4-migration/migrationData.clienttest.ts
index 684b0d3170..6531b594c0 100644
--- a/web/src/features/v4-migration/migrationData.clienttest.ts
+++ b/web/src/features/v4-migration/migrationData.clienttest.ts
@@ -25,6 +25,7 @@ const migrationStatus = (
experiments: loadedAction("not_required"),
apis: loaded(0),
exports: loaded(0),
+ forceV3Experience: false,
...overrides,
});
diff --git a/web/src/features/v4-migration/migrationData.ts b/web/src/features/v4-migration/migrationData.ts
index 342e9f6d06..8332d86b45 100644
--- a/web/src/features/v4-migration/migrationData.ts
+++ b/web/src/features/v4-migration/migrationData.ts
@@ -85,17 +85,27 @@ export type ProjectMigrationStatus = {
experiments: MigrationActionState;
apis: MigrationCountState;
exports: MigrationCountState;
+ // Whether the project is forced onto the v3 experience (partner-managed
+ // upgrade). Always set; `true` short-circuits readiness to "partner-managed".
+ forceV3Experience: boolean;
};
export type ProjectMigrationReadiness =
| "checking"
| "unavailable"
| "ready"
- | "action-needed";
+ | "action-needed"
+ | "partner-managed";
export const getProjectMigrationReadiness = (
status: ProjectMigrationStatus,
): ProjectMigrationReadiness => {
+ // Forced-v3 projects don't migrate themselves β€” their integration partner
+ // does. Surface that instead of any migration action state.
+ if (status.forceV3Experience) {
+ return "partner-managed";
+ }
+
const counts = [status.evals, status.apis, status.exports];
if (
diff --git a/web/src/features/v4-migration/partnerIntegrationDocs.ts b/web/src/features/v4-migration/partnerIntegrationDocs.ts
new file mode 100644
index 0000000000..70a26931f2
--- /dev/null
+++ b/web/src/features/v4-migration/partnerIntegrationDocs.ts
@@ -0,0 +1,6 @@
+// FAQ page for projects kept on the v3 experience because they are instrumented
+// via an integration partner (e.g. VAPI) that has not upgraded to OTEL
+// ingestion yet. The partner performs the upgrade for them; until then the v4
+// migration prompts do not apply. Update the slug once the docs page ships.
+export const PARTNER_INTEGRATION_FAQ_URL =
+ "https://langfuse.com/faq/all/partner-integration-v4-upgrade";
diff --git a/web/src/features/v4-migration/useForceV3Experience.ts b/web/src/features/v4-migration/useForceV3Experience.ts
new file mode 100644
index 0000000000..6dc11d5e66
--- /dev/null
+++ b/web/src/features/v4-migration/useForceV3Experience.ts
@@ -0,0 +1,21 @@
+import { api } from "@/src/utils/api";
+
+/**
+ * Whether the given project is forced onto the v3 experience via
+ * LANGFUSE_FORCE_V3_EXPERIENCE. The value is static per deployment, so it is
+ * cached for the session. Returns false while loading or when no project id is
+ * available (safe default: not forced).
+ */
+export function useForceV3Experience(projectId?: string): boolean {
+ const forceV3 = api.v4Transition.forceV3Experience.useQuery(
+ { projectId: projectId ?? "" },
+ {
+ // Callers that only need the value behind another gate (e.g. the v4
+ // upgrade flag) can pass enabled:false to avoid firing the query for
+ // users the answer can't affect.
+ enabled: Boolean(projectId),
+ staleTime: Infinity,
+ },
+ );
+ return forceV3.data ?? false;
+}
diff --git a/web/src/features/v4-migration/useV4UpgradeUiEnabled.clienttest.ts b/web/src/features/v4-migration/useV4UpgradeUiEnabled.clienttest.ts
index b72b7ff800..9919e0b0a0 100644
--- a/web/src/features/v4-migration/useV4UpgradeUiEnabled.clienttest.ts
+++ b/web/src/features/v4-migration/useV4UpgradeUiEnabled.clienttest.ts
@@ -3,15 +3,37 @@ import { useSession } from "next-auth/react";
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(),
}));
+vi.mock("./useForceV3Experience", () => ({
+ useForceV3Experience: vi.fn(),
+}));
+
const mockUseSession = vi.mocked(useSession);
+const mockUseForceV3Experience = vi.mocked(useForceV3Experience);
+
+const mockSessionFlag = (v4UpgradeUi: boolean) => {
+ mockUseSession.mockReturnValue({
+ data: {
+ user: {
+ admin: false,
+ featureFlags: { v4UpgradeUi },
+ },
+ environment: { enableExperimentalFeatures: false },
+ },
+ } as never);
+};
describe("useV4UpgradeUiEnabled", () => {
+ beforeEach(() => {
+ 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);
@@ -35,18 +57,28 @@ describe("useV4UpgradeUiEnabled", () => {
});
it("enables the UI only when the user flag is set", () => {
- mockUseSession.mockReturnValue({
- data: {
- user: {
- admin: false,
- featureFlags: { v4UpgradeUi: true },
- },
- environment: { enableExperimentalFeatures: false },
- },
- } as never);
+ mockSessionFlag(true);
const { result } = renderHook(() => useV4UpgradeUiEnabled());
expect(result.current).toBe(true);
});
+
+ it("suppresses the UI for projects forced onto the v3 experience", () => {
+ mockSessionFlag(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 5235e7260e..db114a64e3 100644
--- a/web/src/features/v4-migration/useV4UpgradeUiEnabled.ts
+++ b/web/src/features/v4-migration/useV4UpgradeUiEnabled.ts
@@ -1,7 +1,25 @@
import { useSession } from "next-auth/react";
-export function useV4UpgradeUiEnabled(): boolean {
+import { useForceV3Experience } from "@/src/features/v4-migration/useForceV3Experience";
+
+/**
+ * Raw `v4UpgradeUi` feature-preview flag, without the force-v3 suppression.
+ */
+export function useV4UpgradeUiFlag(): boolean {
const { data: session } = useSession();
return session?.user?.featureFlags.v4UpgradeUi === true;
}
+
+/**
+ * Master gate for the v4 migration/upgrade UI. Every migration surface (nav
+ * pill, upgrade badges, panel provider, banner, status page) checks this hook,
+ * so returning false for a forced-v3 project hides all of them at once β€” and
+ * automatically restores the sidebar "V4 Preview" toggle, which only renders
+ * when the migration UI is off.
+ */
+export function useV4UpgradeUiEnabled(projectId?: string): boolean {
+ const flag = useV4UpgradeUiFlag();
+ const forceV3 = useForceV3Experience(projectId);
+ return flag && !forceV3;
+}
diff --git a/web/src/features/v4/server/v4TransitionRouter.ts b/web/src/features/v4/server/v4TransitionRouter.ts
index d6f8ef9934..f56bdbedce 100644
--- a/web/src/features/v4/server/v4TransitionRouter.ts
+++ b/web/src/features/v4/server/v4TransitionRouter.ts
@@ -13,6 +13,7 @@ import {
classifyIngestionSdkVersion,
convertDateToClickhouseDateTime,
INTERNAL_INGESTION_SDK_NAMES,
+ isForceV3ExperienceProject,
logger,
queryClickhouse,
systemTableRef,
@@ -277,6 +278,11 @@ const getLegacyIntegrations = ({
});
export const v4TransitionRouter = createTRPCRouter({
+ // Whether this project is forced onto the v3 experience
+ forceV3Experience: protectedProjectProcedure
+ .input(z.object({ projectId: z.string() }))
+ .query(({ input }) => isForceV3ExperienceProject(input.projectId)),
+
summary: protectedProjectProcedure
.input(z.object({ projectId: z.string() }))
.query(async ({ input, ctx }) => {
@@ -431,6 +437,7 @@ export const v4TransitionRouter = createTRPCRouter({
legacyIntegrationCount:
Object.values(legacyIntegrations).filter(Boolean).length,
legacyIntegrations,
+ forceV3Experience: isForceV3ExperienceProject(project.id),
};
}),
};