remotion-dev/remotion · error · Error

Remotion Lambda can only render based on a URL in the cloud.

Error message

Remotion Lambda can only render based on a URL in the cloud. It seems like you passed a local file: ${urlOrId}. Read the setup guide for Remotion Lambda ${DOCS_URL}/docs/lambda/setup

What it means

convertToServeUrl throws if the serve-url argument starts with 'src/'. Remotion Lambda renders only from a deployed cloud site (an HTTPS URL or a site id), never from local source files. This guard catches the common mistake of passing a local entry point.

Source

Thrown at packages/lambda-client/src/convert-to-serve-url.ts:14

import {DOCS_URL} from '@remotion/serverless-client';
import type {AwsRegion} from './regions';

export const convertToServeUrlImplementation = ({
	urlOrId,
	region,
	bucketName,
}: {
	urlOrId: string;
	region: AwsRegion;
	bucketName: string;
}) => {
	if (urlOrId.startsWith('src/')) {
		throw new Error(
			`Remotion Lambda can only render based on a URL in the cloud. It seems like you passed a local file: ${urlOrId}. Read the setup guide for Remotion Lambda ${DOCS_URL}/docs/lambda/setup`,
		);
	}

	if (urlOrId.startsWith('http://') || urlOrId.startsWith('https://')) {
		return urlOrId;
	}

	return `https://${bucketName}.s3.${region}.amazonaws.com/sites/${urlOrId}/index.html`;
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Deploy your composition to a Lambda site with deploySite() and pass the returned serveUrl (or the site id)
2. Or pass a public HTTPS URL of your bundled Remotion project
3. Never pass a local src/ path to a Lambda render API

Example fix

// before
await renderMediaOnLambda({ serveUrl: 'src/index.ts', composition: 'MyVideo', ... });

// after
const {serveUrl} = await deploySite({ entryPoint: 'src/index.ts', ... });
await renderMediaOnLambda({ serveUrl, composition: 'MyVideo', ... });

function assertServeUrl(url: string) {
  if (url.startsWith('src/')) {
    throw new Error('Pass a deployed site URL or site id, not a local src/ path');
  }
}

const isServeUrl = (v: string): boolean => v.startsWith('http://') || v.startsWith('https://') || !v.startsWith('src/');

When it happens

Trigger: Passing 'src/index.ts', 'src/index.tsx', or any 'src/'-prefixed local path to renderMediaOnLambda's serveUrl (or any API that calls convertToServeUrl).

Common situations: Confusing Remotion Lambda (cloud render) with local renderMedia; forgetting to deploy a site first; copy-pasting a local path.

Related errors

• "serveURL" parameter must be a string, but is ${JSON.stringi
• 'serve_url' parameter is required and cannot be empty or whi
• Image format mismatch: ${outName} was given as the ${outName
• Image format mismatch: ${outName} was given as the ${outName
• Remotion Lambda can only render based on a URL in the cloud.

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