remotion-dev/remotion · error · Error

useCurrentFrame() can only be called inside a component that

Error message

useCurrentFrame() can only be called inside a component that was registered as a composition. See https://www.remotion.dev/docs/the-fundamentals#defining-compositions

What it means

useCurrentFrame() checks the CanUseRemotionHooks context before reading the timeline. When that context is false and the environment is NOT the Player (i.e. Studio/CLI/SSR), this message fires, telling you the calling component was never registered as a <Composition> component.

Source

Thrown at packages/core/src/use-current-frame.ts:22

import {useTimelinePosition} from './timeline-position-state.js';
import {useRemotionEnvironment} from './use-remotion-environment.js';

/*
 * @description Retrieves the current frame of the video within a component. Frames are 0-indexed, and if the component is wrapped in a `<Sequence>`, it returns the frame relative to when the Sequence starts.
 * @see [Documentation](https://www.remotion.dev/docs/use-current-frame)
 */
export const useCurrentFrame = (): number => {
	const canUseRemotionHooks = useContext(CanUseRemotionHooks);
	const env = useRemotionEnvironment();

	if (!canUseRemotionHooks) {
		if (env.isPlayer) {
			throw new Error(
				`useCurrentFrame can only be called inside a component that was passed to <Player>. See: https://www.remotion.dev/docs/player/examples`,
			);
		}

		throw new Error(
			`useCurrentFrame() can only be called inside a component that was registered as a composition. See https://www.remotion.dev/docs/the-fundamentals#defining-compositions`,
		);
	}

	const frame = useTimelinePosition();
	const context = useContext(SequenceContext);

	const contextOffset = context
		? context.cumulatedFrom + context.relativeFrom
		: 0;

	return frame - contextOffset;
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Register the component via <Composition component={MyComp} .../> in your Remotion root.
2. For previews outside Remotion, wrap the component in a <Player> instead of rendering it directly.
3. Remove the useCurrentFrame() call from components that are not part of a composition (pass frame as a prop).

Example fix

// before
ReactDOM.render(<MyComp />, root);

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

// Register the component as a Composition, or wrap it in a Player for standalone use
import {Player} from '@remotion/player';

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

When it happens

Trigger: Calling useCurrentFrame() in a component that is rendered standalone (plain React app, Storybook, unit test) without being registered via <Composition component={...}> or wrapped in a <Player>.

Common situations: Mounting a Remotion component in a design tool or test harness; importing a composition component into a Next.js/CRA page; SSR pre-rendering a component that uses Remotion hooks.

Related errors

• TimelineContext is not available. This hook must be used ins
• useCurrentFrame can only be called inside a component that w
• 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

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