facebook/react · error · Error

startGestureTransition should not be exported when the enabl

Error message

startGestureTransition should not be exported when the enableGestureTransition flag is off.

What it means

startGestureTransition is gated behind the enableGestureTransition build flag; the export exists in the module but throws if invoked from a build where the flag is off. This is an internal invariant ensuring an unstable, flag-disabled API cannot be used accidentally from stable channels.

Source

Thrown at packages/react/src/ReactStartTransition.js:127

              'that you cannot add to the outer Transition while inside the inner.' +
              'This is a bug in React.',
          );
        }
      }
      prevTransition.types = currentTransition.types;
    }
    ReactSharedInternals.T = prevTransition;
  }
}

export function startGestureTransition(
  provider: GestureProvider,
  scope: () => void,
  options?: GestureOptions & StartTransitionOptions,
): () => void {
  if (!enableGestureTransition) {
    // eslint-disable-next-line react-internal/prod-error-codes
    throw new Error(
      'startGestureTransition should not be exported when the enableGestureTransition flag is off.',
    );
  }
  if (provider == null) {
    // We enforce this at runtime even though the type also enforces it since we
    // use null as a signal internally so it would lead it to be treated as a
    // regular transition otherwise.
    throw new Error(
      'A Timeline is required as the first argument to startGestureTransition.',
    );
  }
  const prevTransition = ReactSharedInternals.T;
  const currentTransition: Transition = {} as any;
  if (enableViewTransition) {
    currentTransition.types = null;
  }
  // $FlowFixMe[constant-condition]
  if (enableGestureTransition) {

View on GitHub (pinned to eafeac097b)

Solutions

1. Switch to a React experimental/canary build that has enableGestureTransition enabled (check ReactExperimentalChannel / flags for your version)
2. Remove the startGestureTransition call until the API ships enabled in your channel
3. Verify which React build your bundler resolves (areBuildsEqual / channel checks) so you are not mixing channels

Example fix

// before (stable react)
import {startGestureTransition} from 'react';
startGestureTransition(timeline, () => {...}); // throws

// after
// package.json: "react": "experimental", "react-dom": "experimental"
// then the same call runs with the flag on

// Detect whether the API is usable in this build
import * as React from 'react';
const gestureSupported =
  typeof React.startGestureTransition === 'function' &&
  React.version.includes('experimental');
if (gestureSupported) {
  React.startGestureTransition(timeline, () => animate());
} else {
  animate(); // plain fallback path
}

When it happens

Trigger: Calling React.startGestureTransition (or importing it from 'react') in a build/channel where enableGestureTransition is false — typically the stable or classic release channel.

Common situations: Using experimental gesture/view-transition APIs documented against an experimental React build while running stable React; a bundler resolving 'react' to a different channel than intended after upgrading.

Related errors

• A Timeline is required as the first argument to startGesture
• 349
• Cannot requestFormReset() inside a startGestureTransition. T
• Cannot setState on regular state inside a startGestureTransi
• 343

AI-assisted analysis of facebook/react@eafeac097b (2026-08-21). Data as JSON: /api/errors/d521a4f9a7a86c19. Report an issue: GitHub.