remotion-dev/remotion · error · Error

watchStaticFile() has moved into the `@remotion/studio` pack

Error message

watchStaticFile() has moved into the `@remotion/studio` package. Update your imports.

What it means

Thrown by `watchStaticFile` when `ENABLE_V5_BREAKING_CHANGES` is true. In Remotion v5, `watchStaticFile` has moved out of `remotion`/`@remotion/core` and into `@remotion/studio`. The throw is a hard migration signal: the function still exists in the old location only to fail loudly and tell users to update imports.

Source

Thrown at packages/core/src/watch-static-file.ts:22

type WatcherCallback = (newData: StaticFile | null) => void;

export const WATCH_REMOTION_STATIC_FILES = 'remotion_staticFilesChanged';

export type WatchRemotionStaticFilesPayload = {
	files: StaticFile[];
};

/*
 * @description Watches for changes in a specific static file and invokes a callback function when the file changes, enabling dynamic updates in your Remotion projects.
 * @see [Documentation](https://www.remotion.dev/docs/watchstaticfile)
 */
export const watchStaticFile = (
	fileName: string,
	callback: WatcherCallback,
): {cancel: () => void} => {
	if (ENABLE_V5_BREAKING_CHANGES) {
		throw new Error(
			'watchStaticFile() has moved into the `@remotion/studio` package. Update your imports.',
		);
	}

	// Check if function is called in Remotion Studio
	if (!getRemotionEnvironment().isStudio) {
		// eslint-disable-next-line no-console
		console.warn(
			'The watchStaticFile() API is only available while using the Remotion Studio.',
		);
		return {cancel: () => undefined};
	}

	const withoutStaticBase = fileName.startsWith(window.remotion_staticBase)
		? fileName.replace(window.remotion_staticBase, '')
		: fileName;
	const withoutLeadingSlash = withoutStaticBase.startsWith('/')
		? withoutStaticBase.slice(1)

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Change the import: `import {watchStaticFile} from '@remotion/studio';` instead of from `remotion`.
2. After migrating, ensure the call still only runs inside Remotion Studio (the function warns otherwise).
3. Remove the old import site entirely to avoid accidental re-use.

Example fix

// before
import {watchStaticFile} from 'remotion';

// after
import {watchStaticFile} from '@remotion/studio';

import {ENABLE_V5_BREAKING_CHANGES} from 'remotion/v5-flag';

if (ENABLE_V5_BREAKING_CHANGES) {
  // import watchStaticFile from '@remotion/studio' instead
}

const watchStaticFileLivesInStudio = (): boolean =>
  Boolean(ENABLE_V5_BREAKING_CHANGES);

When it happens

Trigger: Calling `watchStaticFile` imported from `remotion` or `@remotion/core` while running against Remotion v5 (where ENABLE_V5_BREAKING_CHANGES is enabled). The check is the first statement in the function body, so it fires on any call.

Common situations: Upgrading a project to Remotion v5 without migrating the watchStaticFile import; a v4/v5 shared codebase running with the v5 flag flipped on.

Related errors

• getStaticFiles() has moved into the `@remotion/studio` packa
• bundle() no longer supports the legacy positional arguments.
• The config format has changed. Change `Config.Preview.*()` c
• The config format has changed. Change `Config.Bundling.*()`
• The config format has changed. Change `Config.Rendering.*()`

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