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/cloudrun/setup

What it means

Thrown by convertToServeUrl() when the urlOrId argument starts with 'src/' — a path that looks like a local source tree entry rather than a deployed serve URL or site id. Cloud Run (like Lambda) can only render from a publicly reachable URL or a previously deployed site in a GCS bucket; it cannot read your local files. The message misleadingly says 'Remotion Lambda' and links to the cloudrun/setup docs.

Source

Thrown at packages/cloudrun/src/shared/convert-to-serve-url.ts:11

import {DOCS_URL} from './docs-url';

export const convertToServeUrl = ({
	urlOrId,
	bucketName,
}: {
	urlOrId: string;
	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/cloudrun/setup`,
		);
	}

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

	return `https://storage.googleapis.com/${bucketName}/sites/${urlOrId}/index.html`;
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Deploy your bundle as a site first: `npx remotion cloudrun sites create src/index.ts --region=<region>`, then pass the returned site id (or full https URL) as serveUrl.
2. If you already have a hosted bundle, pass the full https URL to it directly.
3. Do not pass a local path like 'src/...'; Cloud Run cannot access your filesystem.

Example fix

// before
await renderMediaOnCloudRun({ serveUrl: 'src/index.ts', composition, codec });
// after
// $ npx remotion cloudrun sites create src/index.ts --region=us-east1
// -> serves returns site id 'my-site'
await renderMediaOnCloudRun({ serveUrl: 'my-site', composition, codec });

function resolveServeUrl(input: string): string {
  if (input.startsWith('src/')) {
    throw new Error('Pass a deployed site id or https URL, not a local path. Run: npx remotion cloudrun sites create');
  }
  return input;
}
await renderMediaOnCloudRun({ serveUrl: resolveServeUrl(myServeUrl), ... });

function isCloudServeUrl(v: string): boolean {
  return v.startsWith('http://') || v.startsWith('https://') || !v.startsWith('src/');
}

try {
  await renderMediaOnCloudRun({ serveUrl, ... });
} catch (err) {
  if (err instanceof Error && err.message.includes('only render based on a URL in the cloud')) {
    throw new Error('Deploy a site first: npx remotion cloudrun sites create src/index.ts');
  }
  throw err;
}

When it happens

Trigger: Passing serveUrl='src/index.ts' or any string beginning with 'src/' to renderMediaOnCloudRun()/renderStillOnCloudRun(). Strings starting with http:// or https:// are returned as-is; anything else is treated as a deployed site id under the bucket.

Common situations: Copy-pasting a Lambda or local CLI example into Cloud Run code; pointing at a relative source path instead of a deployed site; forgetting to run `remotion cloudrun sites create` and using the returned site id.

Related errors

• Bucket creation is required, but no region has been passed.
• Either cloudRunUrl or serviceName must be provided
• Either cloudRunUrl or serviceName must be provided, not both
• If determining Cloudrun Url from serviceName, region must be
• Multiple frame ranges are not supported on Cloud Run. Use re

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