remotion-dev/remotion · error · Error

useCurrentFrame can only be called inside a component that w

Error message

useCurrentFrame can only be called inside a component that was passed to <Player>. See: https://www.remotion.dev/docs/player/examples

What it means

useCurrentFrame() checks the CanUseRemotionHooks context before reading the timeline. When the hook is called outside a Remotion render tree and the environment is the Player, this specific message fires, telling you the calling component is not the one passed to <Player>.

Source

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

import {useContext} from 'react';
import {CanUseRemotionHooks} from './CanUseRemotionHooks.js';
import {SequenceContext} from './SequenceContext.js';
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. Move the useCurrentFrame() call into the component passed to <Player component={...}>.
2. Pass the current frame from the Player via the component prop tree instead of reading it in an outer wrapper.
3. Use the Player's onFrame prop or a ref-based subscription to observe the frame outside the composition.

Example fix

// before
function App() {
  const frame = useCurrentFrame();
  return (
    <>
      <FrameLabel frame={frame} />
      <Player component={Video} {...props} />
    </>
  );
}

// after
function Video() {
  const frame = useCurrentFrame();
  return <FrameLabel frame={frame} />;
}
function App() {
  return <Player component={Video} {...props} />;
}

// Move the hook into the component passed to <Player component={...}/>
function CompositionComponent() {
  const frame = useCurrentFrame();
  return <Overlay frame={frame} />;
}

<Player component={CompositionComponent} {...playerProps} />

When it happens

Trigger: Calling useCurrentFrame() in a component that is rendered outside the <Player component={...}> tree, e.g. as a sibling of <Player>, in a parent that wraps <Player>, or in a controls overlay that is not a child of the Player's component prop.

Common situations: Building custom Player controls or chrome that lives outside the composition component; calling useCurrentFrame() in a hook used by both Player controls and the composition; SSR or preview renders.

Related errors

• TimelineContext is not available. This hook must be used ins
• 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

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