remotion-dev/remotion · error · Error

Remotion Lambda can only render based on a URL in the…

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.

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

• 'serve_url' parameter is required and cannot be empty or…
• "serveURL" parameter must be a string, but is
• 'expiresIn' should be a number, but is
• 'expiresIn' should be an integer but is
• 'expiresIn' should be finite but is

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

Appendix: source

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

import {DOCS_URL} from '@remotion/serverless-client';
import {getAwsRegionMetadata} from './aws-region-metadata';
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;
	}

	const {dnsSuffix} = getAwsRegionMetadata(region);
	return `https://${bucketName}.s3.${region}.${dnsSuffix}/sites/${urlOrId}/index.html`;
};

View on GitHub (pinned to 10db9de073)