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_media.py when REMOTION_APP_SERVE_URL is unset. The serve URL is the location of your bundled Remotion site (a deployed Lambda site URL or a serve-url from `remotion lambda sites deploy`) and the client attaches it to every render request so the renderer knows what to load.

Source

Thrown at packages/lambda-python/testclient_render_media.py:22

import os
from dotenv import load_dotenv
import boto3
from botocore.config import Config

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")


# --- NEW: Create a custom botocore Config for timeouts ---
# This configuration will apply to both S3 and Lambda clients created by RemotionClient
# if passed via the botocore_config parameter.
custom_botocore_config = Config(
    connect_timeout=30,  # Max 30 seconds to establish a connection
    read_timeout=60,     # Max 60 seconds to receive data after connection
    retries={'max_attempts': 3, 'mode': 'adaptive'}, # Retry up to 3 times on certain errors
    # You can add more settings here, e.g., proxies
    # proxies={
    #     'http': 'http://proxy.example.com:8080',
    #     'https': 'https://proxy.example.com:8080'
# }
)
print(f"Created custom botocore config: {custom_botocore_config.retries}")

View on GitHub (pinned to 78fe4bb3fd)

Solutions

  1. Deploy a site: `npx remotion lambda sites deploy src/index.ts` and capture the returned URL.
  2. Add `REMOTION_APP_SERVE_URL=<https URL>` to packages/lambda-python/.env.
  3. Use a publicly reachable URL, not localhost, when invoking Lambda.
  4. Confirm with `npx remotion lambda sites ls`.

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 or not a URL. Run: npx remotion lambda sites deploy')

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

When it happens

Trigger: Running the example without having deployed a site, or with REMOTION_APP_SERVE_URL blank. Also fires if the var was set to a different name like REMOTION_SERVE_URL.

Common situations: Fresh project where `npx remotion lambda sites deploy` was never run; using a localhost serve URL on a remote Lambda (the function cannot reach your machine); URL typos.

Related errors

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