remotion-dev/remotion · error · Error

Studio server port should be a number. Got ${typeof port} ($

Error message

Studio server port should be a number. Got ${typeof port} (${JSON.stringify(port)})

What it means

`setStudioPort` / `setPort` (deprecated alias) in preview-server.ts validate that the supplied port is `number` or `undefined`. Any other JS type (string from env, null, object) throws an Error echoing the actual type and JSON value.

Source

Thrown at packages/cli/src/config/preview-server.ts:11

import {BrowserSafeApis} from '@remotion/renderer/client';
import {parsedCli} from '../parsed-cli';

const {portOption} = BrowserSafeApis.options;

let studioPort: number | undefined;
let rendererPort: number | undefined;

const validatePort = (port: number | undefined) => {
	if (!['number', 'undefined'].includes(typeof port)) {
		throw new Error(
			`Studio server port should be a number. Got ${typeof port} (${JSON.stringify(
				port,
			)})`,
		);
	}

	if (port === undefined) {
		return;
	}

	if (port < 1 || port > 65535) {
		throw new Error(
			`Studio server port should be a number between 1 and 65535. Got ${port}`,
		);
	}
};

/**

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Parse the env value to a number: `Config.setStudioPort(Number(process.env.STUDIO_PORT))`.
Pass `undefined` explicitly when you want Remotion to pick a port.

Example fix

// before
Config.setStudioPort(process.env.STUDIO_PORT);
// after
Config.setStudioPort(
  process.env.STUDIO_PORT ? Number(process.env.STUDIO_PORT) : undefined,
);

Defensive patterns

Strategy: type-guard

Validate before calling

const raw = process.env.STUDIO_PORT;
const port = raw === undefined ? undefined : Number(raw);
if (port !== undefined && Number.isNaN(port)) {
  throw new Error(`STUDIO_PORT must be numeric, got ${raw}`);
}
Config.setStudioPort(port);

Type guard

const isPortInput = (v: unknown): v is number | undefined =>
  v === undefined || (typeof v === 'number' && Number.isFinite(v));

Prevention

Convert env strings with `Number()` and check `Number.isNaN`.
Pass `undefined` rather than a string when you want Remotion to choose.

When it happens

Trigger: Calling `Config.setStudioPort(process.env.STUDIO_PORT)` where the env var is a string; `setStudioPort('3000')`; `setStudioPort(null)`.

Common situations: Reading the port from `process.env` (always string); parsing a config file where the value is quoted; receiving the port over IPC/JSON as a string.

Related errors

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