{"record":{"id":"734a3bd94b98feea","repo":"remotion-dev/remotion","slug":"remotion-lambda-can-only-render-based-on-a-url-in","errorCode":null,"errorMessage":"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","messagePattern":"Remotion Lambda can only render based on a URL in the cloud\\. It seems like you passed a local file: (.+?)\\. Read the setup guide for Remotion Lambda (.+?)/docs/cloudrun/setup","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cloudrun/src/shared/convert-to-serve-url.ts","lineNumber":11,"sourceCode":"import {DOCS_URL} from './docs-url';\n\nexport const convertToServeUrl = ({\n\turlOrId,\n\tbucketName,\n}: {\n\turlOrId: string;\n\tbucketName: string;\n}) => {\n\tif (urlOrId.startsWith('src/')) {\n\t\tthrow new Error(\n\t\t\t`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`,\n\t\t);\n\t}\n\n\tif (urlOrId.startsWith('http://') || urlOrId.startsWith('https://')) {\n\t\treturn urlOrId;\n\t}\n\n\treturn `https://storage.googleapis.com/${bucketName}/sites/${urlOrId}/index.html`;\n};\n","sourceCodeStart":1,"sourceCodeEnd":22,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/cloudrun/src/shared/convert-to-serve-url.ts#L1-L22","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","If you already have a hosted bundle, pass the full https URL to it directly.","Do not pass a local path like 'src/...'; Cloud Run cannot access your filesystem."],"exampleFix":"// before\nawait renderMediaOnCloudRun({ serveUrl: 'src/index.ts', composition, codec });\n// after\n// $ npx remotion cloudrun sites create src/index.ts --region=us-east1\n// -> serves returns site id 'my-site'\nawait renderMediaOnCloudRun({ serveUrl: 'my-site', composition, codec });","handlingStrategy":"validation","validationCode":"function resolveServeUrl(input: string): string {\n  if (input.startsWith('src/')) {\n    throw new Error('Pass a deployed site id or https URL, not a local path. Run: npx remotion cloudrun sites create');\n  }\n  return input;\n}\nawait renderMediaOnCloudRun({ serveUrl: resolveServeUrl(myServeUrl), ... });","typeGuard":"function isCloudServeUrl(v: string): boolean {\n  return v.startsWith('http://') || v.startsWith('https://') || !v.startsWith('src/');\n}","tryCatchPattern":"try {\n  await renderMediaOnCloudRun({ serveUrl, ... });\n} catch (err) {\n  if (err instanceof Error && err.message.includes('only render based on a URL in the cloud')) {\n    throw new Error('Deploy a site first: npx remotion cloudrun sites create src/index.ts');\n  }\n  throw err;\n}","preventionTips":["Always deploy a site first and store the returned site id or URL.","Never pass local filesystem paths to Cloud Run or Lambda render APIs.","Centralize serveUrl resolution in a helper so the rule is enforced once."],"tags":["cloudrun","serve-url","validation","sites"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}