remotion-dev/remotion · error · Error

Pass --out-name when using S3 output provider flags.

Error message

Pass --out-name when using S3 output provider flags.

What it means

The makeOutNameWithCustomCredentials() helper validates that when an S3 output provider is configured via CLI flags, an output key (--out-name) must also be supplied. When writing to a custom S3-compatible destination, Remotion needs the explicit object key to use for the rendered output file, since it cannot derive it from the default naming scheme.

Source

Thrown at packages/lambda/src/cli/helpers/get-s3-output-provider-from-cli.ts:69

	key,
	s3OutputProvider,
}: {
	bucketName: string | undefined;
	key: string | undefined;
	s3OutputProvider: CustomCredentials<AwsProvider> | null;
}): OutNameInput<AwsProvider> | null => {
	if (!s3OutputProvider) {
		return key ?? null;
	}

	if (!bucketName) {
		throw new Error(
			'Pass --force-bucket-name when using S3 output provider flags.',
		);
	}

	if (!key) {
		throw new Error('Pass --out-name when using S3 output provider flags.');
	}

	return {
		bucketName,
		key,
		s3OutputProvider,
	};
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Add the --out-name=<key> flag (e.g. --out-name=renders/output.mp4) when using S3 output provider flags.
2. Ensure the key includes the desired path and filename within the bucket.
3. Remove all S3 output provider flags if you want Remotion to use its default output naming.

Example fix

# before
npx remotion lambda render MyComp \
  --s3-output-provider-endpoint=https://s3.example.com \
  --force-bucket-name=my-render-bucket

# after
npx remotion lambda render MyComp \
  --s3-output-provider-endpoint=https://s3.example.com \
  --force-bucket-name=my-render-bucket \
  --out-name=renders/output.mp4

function validateS3OutputProviderOutName(opts: {
  s3OutputProvider: unknown;
  key?: string;
}): void {
  if (opts.s3OutputProvider && !opts.key) {
    throw new Error('--out-name is required when using S3 output provider flags.');
  }
}

When it happens

Trigger: Running a Lambda CLI command with S3 output provider flags and a forced bucket name but without --out-name. The function has already confirmed s3OutputProvider and bucketName are non-null, and now requires key to be set.

Common situations: User provides the endpoint and bucket for a custom S3 output but omits the output file name/key; user expects Remotion to generate a default key on the custom endpoint.

Related errors

• Pass --s3-output-provider-endpoint when using S3 output prov
• Pass --force-bucket-name when using S3 output provider flags
• maxRetries is NaN
• maxRetries cannot be negative but is ${maxRetries}
• maxRetries should be an integer, but is ${maxRetries}.

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