What causes "REMOTION_APP_SERVE_URL is not set" in remotion-dev/remotion?

Deploy a site and capture its URL.

remotion-dev/remotion · error · Exception

REMOTION_APP_SERVE_URL is not set

Error message

REMOTION_APP_SERVE_URL is not set

What it means

Raised by testclient_render_still.py when REMOTION_APP_SERVE_URL is unset. The still renderer needs the bundled site URL to know which composition to capture a still from.

Source

Thrown at packages/lambda-python/testclient_render_still.py:21

from remotion_lambda import RenderStillParams, Privacy, ValidStillImageFormats
from remotion_lambda import RemotionClient
from dotenv import load_dotenv


load_dotenv()

# Load env variables
REMOTION_APP_REGION = os.getenv('REMOTION_APP_REGION')
if not REMOTION_APP_REGION:
    raise Exception("REMOTION_APP_REGION is not set")

REMOTION_APP_FUNCTION_NAME = os.getenv('REMOTION_APP_FUNCTION_NAME')
if not REMOTION_APP_FUNCTION_NAME:
    raise Exception("REMOTION_APP_FUNCTION_NAME is not set")

REMOTION_APP_SERVE_URL = os.getenv('REMOTION_APP_SERVE_URL')
if not REMOTION_APP_SERVE_URL:
    raise Exception("REMOTION_APP_SERVE_URL is not set")

# Construct client
client = RemotionClient(region=REMOTION_APP_REGION,
                        serve_url=REMOTION_APP_SERVE_URL,
                        function_name=REMOTION_APP_FUNCTION_NAME)

# Set render still request
render_params = RenderStillParams(
    composition="still-helloworld",
    privacy=Privacy.PUBLIC,
    image_format=ValidStillImageFormats.JPEG,
    input_props={
        'message': 'Hello from props!'
    },
)

render_response = client.render_still_on_lambda(render_params)
if render_response:

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Deploy a site and capture its URL.
Add `REMOTION_APP_SERVE_URL=<public URL>` to .env.
Confirm the site is reachable from the Lambda's VPC.
Run from the package directory so .env loads.

Example fix

// before
REMOTION_APP_SERVE_URL=
// after
REMOTION_APP_SERVE_URL=https://remotionlambda-123.s3.us-east-1.amazonaws.com/sites/abc/index.html

Defensive patterns

Strategy: validation

Validate before calling

import os
url = os.getenv('REMOTION_APP_SERVE_URL')
if not url or not url.startswith('http'):
    raise SystemExit('REMOTION_APP_SERVE_URL is not set')

Type guard

def is_http_url(v): return isinstance(v, str) and v.startswith(('http://', 'https://'))

Try / catch

try:
    assert os.getenv('REMOTION_APP_SERVE_URL', '').startswith('http')
except AssertionError:
    sys.exit(3)

Prevention

Deploy the site once and reuse its URL for both media and still examples.
Use a public URL; Lambda cannot reach localhost.
Redeploy the site when compositions change.
Keep the URL in .env under the exact variable name.

When it happens

Trigger: Running the still example without deploying a site, or with REMOTION_APP_SERVE_URL blank.

Common situations: `npx remotion lambda sites deploy` never run; URL set to localhost (unreachable from Lambda); var renamed.

Related errors

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