facebook/react · error · Error

A Timeline is required as the first argument to startGesture

Error message

A Timeline is required as the first argument to startGestureTransition.

What it means

startGestureTransition requires a Timeline (gesture provider) as its first argument; null/undefined is rejected at runtime even though TypeScript also forbids it, because null is used internally as the signal for a regular transition and would silently change semantics.

Source

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

  }
}

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) {
    currentTransition.gesture = provider;
  }
  if (enableTransitionTracing) {
    currentTransition.name =
      options !== undefined && options.name !== undefined ? options.name : null;
    currentTransition.startTime = -1; // TODO: This should read the timestamp.
  }
  if (__DEV__) {

View on GitHub (pinned to eafeac097b)

Solutions

1. Create the Timeline/gesture provider first and pass it as the first argument
2. Guard the call: if (timeline != null) startGestureTransition(timeline, ...)
3. Fix the construction order so the provider exists before any gesture transition starts

Example fix

// before
const timeline = maybeTimeline; // possibly null
startGestureTransition(timeline, () => { animate(); });

// after
if (timeline != null) {
  startGestureTransition(timeline, () => { animate(); });
}

// Validate the provider before starting the gesture transition
if (timeline != null && typeof timeline === 'object') {
  startGestureTransition(timeline, () => animate());
} else {
  animate(); // or start a regular startTransition
}

const isGestureProvider = (v: unknown): v is GestureProvider =>
  v != null && typeof v === 'object';

When it happens

Trigger: Calling startGestureTransition(null, scope) or startGestureTransition(undefined, scope) — e.g. the provider variable is optional and was not created before the call.

Common situations: Gesture/Timeline object created lazily or conditionally and not yet initialized when the transition starts; refactoring from an older signature where the provider was optional.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• startGestureTransition should not be exported when the enabl
• 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/9f2abc1dbd0c8329. Report an issue: GitHub.