remotion-dev/remotion · error · Error

Pass --force-bucket-name when using S3 output provider flags

Error message

Pass --force-bucket-name when using S3 output provider flags.

What it means

The makeOutNameWithCustomCredentials() helper validates that when an S3 output provider is configured (from CLI flags), a forced bucket name must be supplied via --force-bucket-name. When using a custom S3-compatible output, Remotion cannot auto-generate a bucket name, so the user must specify exactly which bucket to write to.

Source

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

		forcePathStyle,
	};
};

export const makeOutNameWithCustomCredentials = ({
	bucketName,
	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 --force-bucket-name=<your-bucket> flag when using S3 output provider flags.
2. Ensure the bucket exists on the custom S3 endpoint and is writable with the provided credentials.
3. Remove all S3 output provider flags if you want Remotion to manage buckets on its own (default S3 behavior).

Example fix

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

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

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

When it happens

Trigger: Running a Lambda CLI command with S3 output provider flags (endpoint, region, force-path-style) but without --force-bucket-name. Since s3OutputProvider is non-null, the function requires bucketName to be set.

Common situations: User sets up a custom S3 output endpoint but forgets to specify the target bucket; user expects Remotion to create or pick a bucket on the custom endpoint automatically.

Related errors

• Pass --s3-output-provider-endpoint when using S3 output prov
• Pass --out-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/ecbee37d27ec6b91. Report an issue: GitHub.