remotion-dev/remotion · error · RemotionInvalidArgumentException

'serve_url' parameter is required and cannot be empty or whi

Error message

'serve_url' parameter is required and cannot be empty or whitespace

What it means

Constructor-time validation in the Python RemotionClient. Raised when the 'serve_url' argument is None, empty, or whitespace-only. serve_url points to the deployed Remotion bundle (a Studio URL or an S3-hosted entry point URL) and is mandatory for every render call.

Source

Thrown at packages/lambda-python/remotion_lambda/remotionclient.py:169

        ...     session=session,
        ...     config=config
        ... )

        Legacy usage (deprecated):

        >>> client = RemotionClient(
        ...     region='us-east-1',
        ...     serve_url='https://api.example.com',
        ...     function_name='my-function',
        ...     access_key='AKIA...',
        ...     secret_key='secret...'
        ... )
        """
       # Validate required parameters at construction time
        if not region or not region.strip():
            raise RemotionInvalidArgumentException("'region' parameter is required and cannot be empty or whitespace")
        if not serve_url or not serve_url.strip():
            raise RemotionInvalidArgumentException("'serve_url' parameter is required and cannot be empty or whitespace")
        if not function_name or not function_name.strip():
            raise RemotionInvalidArgumentException("'function_name' parameter is required and cannot be empty or whitespace")


        # Check for conflicting authentication methods
        if session and (access_key or secret_key):
            raise RemotionInvalidArgumentException(
                "Cannot specify both 'session' and explicit credentials "
                "('access_key'/'secret_key'). Please use only 'session'."
            )

        # Handle deprecated credential parameters
        if access_key is not None or secret_key is not None:
            warnings.warn(
                "Parameters 'access_key' and 'secret_key' are deprecated "
                "as of version 4.0.376 and will be removed in version 5.0.0. "
                "Please migrate to using 'session' for improved security. ",
                DeprecationWarning,

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Deploy the bundle first (`remotion lambda sites create` / `functions deploy`) and capture the printed serveUrl.
2. Pass the full URL (e.g. 'https://remotionlambda-....s3.region.amazonaws.com') as serve_url.
3. Load serve_url from config with a fallback guard that fails loudly if missing.

Example fix

// before
client = RemotionClient(
    region=region,
    serve_url='',  # forgot to set
    function_name=fn,
)

# after
serve_url = config.get('serve_url')
if not serve_url:
    raise RuntimeError('Run `remotion lambda sites create` first and set serve_url')
client = RemotionClient(
    region=region,
    serve_url=serve_url,
    function_name=fn,
)

from urllib.parse import urlparse

def validate_serve_url(url: str) -> str:
    if not url or not url.strip():
        raise ValueError('serve_url required')
    parsed = urlparse(url.strip())
    if parsed.scheme not in ('http', 'https') or not parsed.netloc:
        raise ValueError(f'invalid serve_url: {url!r}')
    return url.strip()

def is_valid_serve_url(value) -> bool:\n    if not isinstance(value, str) or not value.strip():\n        return False\n    p = urlparse(value.strip())\n    return p.scheme in ('http', 'https') and bool(p.netloc)

try:\n    client = RemotionClient(region=region, serve_url=serve_url, function_name=fn)\nexcept RemotionInvalidArgumentException as e:\n    raise SystemExit(f'serve_url misconfigured: {e}')

When it happens

Trigger: Instantiating RemotionClient with serve_url=None, '', or a whitespace string; passing a serve_url value read from a missing config key; forgetting to deploy the bundle first and so having no URL to pass.

Common situations: Skipping the `npx remotion lambda functions deploy` step; pointing at the wrong environment's URL; passing the S3 bucket name instead of the full serve URL; misreading deploy output that lists serveUrl separately from functionName.

Related errors

• 'function_name' parameter is required and cannot be empty or
• Remotion Lambda can only render based on a URL in the cloud.
• "serveURL" parameter must be a string, but is ${JSON.stringi
• 'region' parameter is required and cannot be empty or whites
• Invalid Lambda invocation parameters: {e}

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