Skip to main content

Troubleshooting

Engine script not loading​

Problem: The engine script doesn't appear in the DOM, or the request fails.

Solutions:

  • Open DevTools → Network, filter for engine.js. It should return 200 from cdn.splitlab.io.
  • If you see a failed request to staging-svc.mvtlab.io, you are on an old release (< 0.2.1) whose default engine URL pointed at the retired host. Upgrade to @splitlabio/nextjs-orchestrator@^0.2.1, or pass the engineUrl prop explicitly.
  • Verify orchestratorKey is the correct project key from your Splitlab dashboard.
  • Confirm the project's domain matches the websiteUrl configured in Splitlab.
  • If using MVTOrchestrator, ensure its file has 'use client'; at the top.

Anti-flicker not working (page flashes)​

Problem: The page stays hidden, or a flash still occurs on first load.

Solutions:

  • Use MVTScripts in layout.tsx instead of MVTOrchestrator. The client-side approach injects after hydration and cannot prevent the initial SSR flash.
  • Verify antiFlickerEnabled={true} (the default).
  • Check that window.rmfk() is being called by the engine (inspect the console).
  • Increase antiFlickerTimeoutMs if the engine takes longer to load.
  • Disable anti-flicker in development if it gets in the way: antiFlickerEnabled={false}.

Duplicate script tags​

Problem: Multiple engine <script> tags are injected.

Solutions:

  • Mount MVTScripts or MVTOrchestrator once at the root — not both independently.
  • When you use both together, MVTOrchestrator auto-detects the MVTScripts-injected id="mvt-engine-script" and skips re-injection.
  • Ensure the component isn't being remounted unnecessarily.

TypeScript errors​

Problem: TypeScript can't find the types.

Solutions:

  • Ensure @types/react and @types/react-dom are installed.
  • Restart the TypeScript server in your IDE.
  • Both MVTScriptsProps and MVTOrchestratorProps are exported from @splitlabio/nextjs-orchestrator.

SSR errors about window / document​

Problem: Errors about window or document being undefined.

Solutions:

  • MVTScripts is a Server Component and touches no DOM at runtime — prefer it in the App Router.
  • If using MVTOrchestrator, make sure its file has 'use client'; at the top and that it is not imported into a Server Component. All of its DOM access already runs inside useEffect.