remotion-dev/remotion · error · Error

usePixelDensity() was called outside of a Remotion context.

Error message

usePixelDensity() was called outside of a Remotion context.
This hook can only be called in a component that is being rendered by Remotion.
If you want this hook to return the browser pixel density outside of Remotion, pass {dontThrowIfOutsideOfRemotion: true} as an option.
If you think you called this hook in a Remotion component, make sure all versions of Remotion are aligned.

What it means

usePixelDensity throws when there is no PixelDensityContext value AND the CanUseRemotionHooks flag is false (i.e. the component is not inside a Remotion render tree) and the caller did not opt into {dontThrowIfOutsideOfRemotion: true}. It protects against calling the hook in plain React/browser code where no Remotion provider is mounted.

Source

Thrown at packages/core/src/use-pixel-density.ts:34

};

/*
 * @description Retrieves the current pixel density. In previews, this corresponds to `window.devicePixelRatio`. During renders, this corresponds to the `scale` option.
 * @see [Documentation](https://www.remotion.dev/docs/use-pixel-density)
 */
export const usePixelDensity = (options?: Options): number => {
	const pixelDensity = useContext(PixelDensityContext);
	const canUseRemotionHooks = useContext(CanUseRemotionHooks);

	if (pixelDensity !== null) {
		return pixelDensity;
	}

	if (canUseRemotionHooks || options?.dontThrowIfOutsideOfRemotion) {
		return getBrowserPixelDensity();
	}

	throw new Error(
		[
			'usePixelDensity() was called outside of a Remotion context.',
			'This hook can only be called in a component that is being rendered by Remotion.',
			'If you want this hook to return the browser pixel density outside of Remotion, pass {dontThrowIfOutsideOfRemotion: true} as an option.',
			'If you think you called this hook in a Remotion component, make sure all versions of Remotion are aligned.',
		].join('\n'),
	);
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Only call usePixelDensity inside components rendered by Remotion (Composition/Player).
2. If you need the value outside Remotion, call usePixelDensity({dontThrowIfOutsideOfRemotion: true}) to fall back to window.devicePixelRatio.
3. Wrap your test/demo tree in the Remotion providers so the context is populated.
4. Split the component: a Remotion-specific version using the hook and a plain version for non-Remotion use.

Example fix

// before
const dpr = usePixelDensity();

// after (outside Remotion)
const dpr = usePixelDensity({dontThrowIfOutsideOfRemotion: true});

// If the component may render outside Remotion:
const dpr = usePixelDensity({ dontThrowIfOutsideOfRemotion: true });

// Wrap usage so non-Remotion contexts degrade gracefully
function safePixelDensity() {
  try {
    return usePixelDensity();
  } catch {
    return typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1;
  }
}

When it happens

Trigger: Calling usePixelDensity() in a component rendered outside <RemotionRoot>/<Composition>/Player; calling it during SSR with no context; calling it in a Storybook or standalone demo without Remotion providers; calling it in a Node script.

Common situations: Sharing a component between a Remotion video and a regular React app; unit-testing a component that calls usePixelDensity without the provider; extracting a sub-component into a library used outside Remotion.

Related errors

• useLogLevel must be used within a LogLevelProvider
• useMountTime must be used within a LogLevelProvider
• useMediaPlayback must be used inside a <BufferingContext>
• No video config found. Likely reasons:- You are probably cal
• No video config found. You are probably calling useVideoConf

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