remotion-dev/remotion · error · Error

Tried to enable the buffering state, but a Remotion context

Error message

Tried to enable the buffering state, but a Remotion context was not found. This API can only be called in a component that was passed to the Remotion Player or a <Composition>. Or you might have experienced a version mismatch - run `npx remotion versions` and ensure all packages have the same version. This error is thrown by the buffer state https://remotion.dev/docs/player/buffer-state

What it means

useBufferState() returns a `delayPlayback()` function used to tell the Player to wait (e.g. while media buffers). delayPlayback() reads the BufferingContextReact; when that context is absent the function throws, because delaying playback has no effect outside a Player/Composition. The error also calls out a possible version mismatch, since mismatched @remotion/* packages can each ship their own context object.

Source

Thrown at packages/core/src/use-buffer-state.ts:26

};

export type UseBufferState = {
	delayPlayback: () => DelayPlaybackHandle;
};

export const useBufferState = (): UseBufferState => {
	const buffer = useContext(BufferingContextReact);
	const logLevel = useLogLevel();

	// Allows <Img> tag to be rendered without a context
	// https://github.com/remotion-dev/remotion/issues/4007
	const addBlock = buffer ? buffer.addBlock : null;

	return useMemo(
		() => ({
			delayPlayback: () => {
				if (!addBlock) {
					throw new Error(
						'Tried to enable the buffering state, but a Remotion context was not found. This API can only be called in a component that was passed to the Remotion Player or a <Composition>. Or you might have experienced a version mismatch - run `npx remotion versions` and ensure all packages have the same version. This error is thrown by the buffer state https://remotion.dev/docs/player/buffer-state',
					);
				}

				Log.trace(
					{logLevel, tag: '[buffer-state]'},
					'Adding buffer handle',
					new Error().stack,
				);

				const {unblock} = addBlock({
					id: String(Math.random()),
				});

				let unblocked = false;

				return {
					unblock: () => {

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Ensure the component calling delayPlayback() is rendered inside a <Player> or <Composition>.
2. Run `npx remotion versions` and align every @remotion/* package to the same version (dedupe with your package manager).
3. Guard the call: only invoke delayPlayback() when you know the component is Player-mounted.

Example fix

// before
const {delayPlayback} = useBufferState();
delayPlayback();

// after
const {delayPlayback} = useBufferState();
if (env.isPlayer || env.isStudio) {
  const handle = delayPlayback();
  // ...
}

import {useRemotionEnvironment} from '@remotion/core';

const {delayPlayback} = useBufferState();
const env = useRemotionEnvironment();
if (env.isPlayer || env.isStudio) {
  const handle = delayPlayback();
  // ...later: handle.unblock();
}

const canUseBufferState = () => {
  const env = useRemotionEnvironment();
  return env.isPlayer || env.isStudio;
};

try {
  return delayPlayback();
} catch (e) {
  if (/buffer state/.test((e as Error).message)) {
    return {unblock: () => undefined};
  }
  throw e;
}

When it happens

Trigger: Calling `useBufferState().delayPlayback()` from a component rendered outside <Player>/<Composition>, or when BufferingContextReact is unavailable because of a version mismatch across @remotion packages.

Common situations: Reusing a buffering-aware media component in a plain React preview; SSR usage; multiple copies of @remotion/core installed via overlapping dependency trees so the context object identity differs.

Related errors

• useCurrentScale() was called outside of a Remotion context.
• 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
• useCurrentFrame can only be called inside a component that w

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