remotion-dev/remotion · error · Error

restartStudio() is not supported in Browser Studio

Error message

restartStudio() is not supported in Browser Studio

What it means

`restartStudio()` from `@remotion/studio` restarts the Node-based Remotion Studio by POSTing to `/api/restart-studio`. Browser Studio (the fully in-browser Studio host, detected via `window.remotion_browserStudio`, set through the 'remotion-browser-studio-operations-ready' handshake) has no Node server to restart, so the function throws before making any request. The error means the call is valid only in the desktop/dev-server Studio.

Source

Thrown at packages/studio/src/api/restart-studio.ts:17

/**
 * @description Restarts the Remotion Studio.
 * @see [Documentation](https://www.remotion.dev/docs/studio/restart-studio)
 */

import type {RestartStudioResponse} from '@remotion/studio-shared';
import {getRemotionEnvironment} from 'remotion';
import {callApi} from '../components/call-api';
import {getBrowserStudioOperations} from '../helpers/browser-studio-operations';

export const restartStudio = (): Promise<RestartStudioResponse> => {
	if (!getRemotionEnvironment().isStudio) {
		throw new Error('restartStudio() is only available in the Studio');
	}

	if (getBrowserStudioOperations() !== null) {
		throw new Error('restartStudio() is not supported in Browser Studio');
	}

	if (window.remotion_isReadOnlyStudio) {
		throw new Error('restartStudio() is not available in read-only Studio');
	}

	return callApi('/api/restart-studio', {});
};

View on GitHub (pinned to 10db9de073)

Solutions

1. Do not call `restartStudio()` in hosted/browser contexts: guard with `getRemotionEnvironment().isStudio` plus a check that `(window as any).remotion_browserStudio` is null.
2. In Browser Studio, trigger a restart by reloading the host page or using the host-provided restart mechanism instead of this API.
3. If you need server-restart behavior, run the standard Studio locally with `npx remotion studio` and invoke `restartStudio()` there.

Example fix

// before
import {restartStudio} from '@remotion/studio';
await restartStudio(); // throws in Browser Studio

// after
import {getRemotionEnvironment} from 'remotion';
import {restartStudio} from '@remotion/studio';

const w = window as unknown as {remotion_browserStudio?: unknown};
if (getRemotionEnvironment().isStudio && w.remotion_browserStudio == null) {
  await restartStudio();
} else {
  window.location.reload(); // browser-safe restart
}

import {getRemotionEnvironment} from 'remotion';

const w = window as unknown as {remotion_browserStudio?: unknown; remotion_isReadOnlyStudio?: boolean};
const canRestart =
  getRemotionEnvironment().isStudio &&
  w.remotion_browserStudio == null &&
  !w.remotion_isReadOnlyStudio;

if (canRestart) {
  const {restartStudio} = await import('@remotion/studio');
  await restartStudio();
}

import {getRemotionEnvironment} from 'remotion';

const isRestartableStudio = (): boolean =>
  getRemotionEnvironment().isStudio &&
  (window as unknown as {remotion_browserStudio?: unknown}).remotion_browserStudio == null &&
  !(window as unknown as {remotion_isReadOnlyStudio?: boolean}).remotion_isReadOnlyStudio;

try {
  await restartStudio();
} catch (err) {
  if (err instanceof Error && err.message.includes('not supported in Browser Studio')) {
    window.location.reload(); // graceful degradation in hosted Studio
  } else {
    throw err;
  }
}

When it happens

Trigger: Calling `restartStudio()` (e.g. from a Studio menu item, custom UI `onClick`, or a hotkey handler) while Studio is embedded in Browser Studio, where `getBrowserStudioOperations()` returns a non-null `window.remotion_browserStudio`. The guard at packages/studio/src/api/restart-studio.ts:16 fires before the `/api/restart-studio` API call.

Common situations: Studio code shared between the regular dev-server Studio and Browser Studio (e.g. remotion.dev embedded Studio or the `browser-studio` package host); clicking a 'Restart Studio' button or programmatically restarting after a config change in that hosted environment; version mismatches where the host page always injects `remotion_browserStudio`.

Related errors

• restartStudio() is not available in read-only Studio
• restartStudio() is only available in the Studio
• shutDownStudio() is only available in the Studio
• shutDownStudio() is not supported in Browser Studio
• Failed to create WebGL shader

AI-assisted analysis of remotion-dev/remotion@10db9de073 (2026-08-22). Data as JSON: /api/errors/b420fd22c0e4e731. Report an issue: GitHub.