remotion-dev/remotion · error · TypeError

"cloudRunUrl" parameter must be a string, but is ${JSON.stri

Error message

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

What it means

Thrown by validateCloudRunUrl() when cloudRunUrl is not a string. The validator is intentionally minimal — it only checks the type, not the URL shape (the comment notes a future endpoint check). It exists to fail fast before the URL is used to invoke the Cloud Run service.

Source

Thrown at packages/cloudrun/src/shared/validate-cloudrun-url.ts:3

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

// To improve this, we could add an endpoint within the image that returns some message to confirm that this is a Cloud Run url

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Ensure cloudRunUrl is a string before calling the API.
Read the deployed service's URL from the deploy result object and store it explicitly.
Add a startup check that the env var (e.g., REMOTION_CLOUDRUN_URL) is set.

Example fix

// before
const { serviceUrl } = config; // undefined when missing
await renderMediaOnCloudRun({ cloudRunUrl: serviceUrl, ... });
// after
const cloudRunUrl = config.serviceUrl;
if (typeof cloudRunUrl !== 'string') throw new Error('cloudRunUrl missing in config');
await renderMediaOnCloudRun({ cloudRunUrl, ... });

Defensive patterns

Strategy: type-guard

Validate before calling

import { validateCloudRunUrl } from '@remotion/cloudrun/shared';
validateCloudRunUrl(cloudRunUrl);

Type guard

function isCloudRunUrlString(v: unknown): v is string {
  return typeof v === 'string';
}

Try / catch

if (typeof cloudRunUrl !== 'string') throw new TypeError('cloudRunUrl must be a string');

Prevention

Store the deployed service URL immediately from the deploy result.
Assert env vars are set at process start.
Avoid deriving the URL from untyped JSON without a type check.

When it happens

Trigger: Passing a non-string cloudRunUrl (undefined, null, object, number) to deployService(), renderMediaOnCloudRun(), or any API that validates the service URL.

Common situations: Reading the URL from an unset env var; passing a service object instead of its .uri string; deserializing config from JSON where the field is missing.

Related errors

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