remotion-dev/remotion · error · TypeError

"serveURL" parameter must be a string, but is ${JSON.stringi

Error message

"serveURL" parameter must be a string, but is ${JSON.stringify(serveUrl)}

What it means

Thrown by validateServeUrl() in @remotion/cloudrun when the serveUrl argument is not a string. The serveUrl points to the deployed Cloud Run serve bundle (often a Google Cloud Storage URL) that handles render requests, and the validator needs a string before it can inspect or fetch the URL.

Source

Thrown at packages/cloudrun/src/shared/validate-serveurl.ts:5

import {getCloudStorageClient} from '../api/helpers/get-cloud-storage-client';

export const validateServeUrl = async (serveUrl: unknown) => {
	if (typeof serveUrl !== 'string') {
		throw new TypeError(
			`"serveURL" parameter must be a string, but is ${JSON.stringify(
				serveUrl,
			)}`,
		);
	}

	// if GCP Storage URL, validate that file exists
	if (serveUrl.startsWith('https://storage.googleapis.com')) {
		const cloudStorageClient = getCloudStorageClient();

		const bucketName = serveUrl.split('/')[3];
		const fileName = serveUrl.split('/').slice(4).join('/');
		const siteName = serveUrl.split('/')[5];

		const [exists] = await cloudStorageClient
			.bucket(bucketName)
			.file(fileName)
			.exists();

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Confirm the serveUrl variable is assigned and is a string before calling the API.
2. Check the env var / config key name for typos.
3. Pass the .url (or equivalent string field) of a deployment result, not the whole object.

Example fix

// before
renderMediaOnCloudRun({ serveUrl: deployment, ... }); // deployment is an object

// after
renderMediaOnCloudRun({ serveUrl: deployment.url, ... });

if (typeof serveUrl !== 'string' || serveUrl.length === 0) {
  throw new TypeError('serveUrl must be a non-empty string');
}

const isServeUrl = (v: unknown): v is string =>
  typeof v === 'string' && v.length > 0;

When it happens

Trigger: Calling renderMediaOnCloudRun (or a related API) with a serveUrl that is undefined, null, a number, an object, or an array. Common when the URL is read from an environment variable that was not set, or constructed conditionally and left undefined.

Common situations: Forgetting to set the SERVE_URL env var; reading from a config object with a typo'd key (returns undefined); passing the deployment object instead of its url property.

Related errors

• maxRetries must be a number, but is ${JSON.stringify(maxRetr
• "serviceName" parameter must be a string, but is ${JSON.stri
• The 'siteName' argument must be a string if provided, but is
• Bucket creation is required, but no region has been passed.
• 'bucketName' must be a string, but is ${JSON.stringify(bucke

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