remotion-dev/remotion · error · Error

TimelineContext is not available. This hook must be used ins

Error message

TimelineContext is not available. This hook must be used inside a <Player> or the Remotion Studio.

What it means

useTimelineContext() reads Remotion's timeline React context, which is provided by <Player>, the Remotion Studio, or a <Composition>'s runtime tree. When the context is null the hook throws immediately, because there is no meaningful frame to return outside of a Remotion-driven render.

Source

Thrown at packages/core/src/timeline-position-state.ts:79

	const env = useRemotionEnvironment();

	if (!videoConfig) {
		return typeof window === 'undefined'
			? 0
			: (window.remotion_initialFrame ?? 0);
	}

	const unclamped =
		state.frame[videoConfig.id] ??
		(env.isPlayer ? 0 : getFrameForComposition(videoConfig.id));

	return clampFrameToCompositionRange(unclamped, videoConfig.durationInFrames);
};

export const useTimelineContext = (): TimelineContextValue => {
	const state = useContext(TimelineContext);
	if (state === null) {
		throw new Error(
			'TimelineContext is not available. This hook must be used inside a <Player> or the Remotion Studio.',
		);
	}

	return state;
};

export const usePlaybackRate = (): PlaybackRateContextValue => {
	const state = useContext(PlaybackRateContext);
	if (state === null) {
		throw new Error(
			'PlaybackRateContext is not available. This hook must be used inside a <Player> or the Remotion Studio.',
		);
	}

	return state;
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Render the component inside a <Player> or as a registered <Composition> component.
2. For tests, wrap the component in a <Player> with a dummy composition.
3. Run `npx remotion versions` to confirm all @remotion/* packages share one version.

Example fix

// before
render(<MyRemotionComponent />);

// after
render(
  <Player
    component={MyRemotionComponent}
    durationInFrames={30}
    fps={30}
    width={640}
    height={360}
  />
);

// Wrap standalone usage in a Player for tests/previews
import {Player} from '@remotion/player';

render(
  <Player
    component={MyComp}
    durationInFrames={30}
    fps={30}
    width={640}
    height={360}
  />,
);

try {
  const state = useTimelineContext();
} catch (e) {
  // not in a Player/Studio; fall back to a default frame
}

When it happens

Trigger: Calling useTimelineContext(), useTimelinePosition(), usePlayingState(), or useTimelineSetFrame() from a component rendered outside any <Player>/<Composition> (e.g. in a Storybook story, a plain React app, or a unit test without a Player wrapper).

Common situations: Reusing a Remotion component in a non-Remotion React app; mounting a component in isolation for testing; version mismatches where the context provider comes from a different Remotion install than the hook.

Related errors

• PlaybackRateContext is not available. This hook must be used
• AbsoluteTimeContext is not available. This hook must be used
• Tried to enable the buffering state, but a Remotion context
• useCurrentFrame can only be called inside a component that w
• useCurrentFrame() can only be called inside a component that

AI-assisted analysis of remotion-dev/remotion@78fe4bb3fd (2026-08-12). Data as JSON: /api/errors/b724d6b6efd0a751. Report an issue: GitHub.