remotion-dev/remotion · warning · Error

A file was found in the bucket "${bucketName}" with the key

Error message

A file was found in the bucket "${bucketName}" with the key ${file.Key} which is an unexpected folder structure. Delete this file.

What it means

getSites lists objects under the sites/ prefix and expects each key to match sites/<siteId>/<rest>. If a key does not match that regex, this error is thrown, naming the offending bucket and key. It indicates bucket pollution — a file living under sites/ that is not part of a valid site.

Source

Thrown at packages/lambda-client/src/get-sites.ts:85

	const sites: {[key: string]: Site} = {};

	for (const bucket of remotionBuckets) {
		const ls = await providerSpecifics.listObjects({
			bucketName: bucket.name,
			prefix: getSitesKey(''),
			region,
			expectedBucketOwner: accountId,
			forcePathStyle,
			requestHandler,
		});

		for (const file of ls) {
			const siteKeyMatch = file.Key?.match(
				/sites\/([0-9a-zA-Z-!_.*'()]+)\/(.*)$/,
			);
			if (!siteKeyMatch) {
				throw new Error(
					`A file was found in the bucket "${bucket.name}" with the key ${file.Key} which is an unexpected folder structure. Delete this file.`,
				);
			}

			const [, siteId] = siteKeyMatch;
			if (!sites[siteId]) {
				sites[siteId] = {
					sizeInBytes: 0,
					bucketName: bucket.name,
					lastModified: null,
					id: siteId,
					serveUrl: makeS3ServeUrl({
						bucketName: bucket.name,
						region,
						subFolder: getSitesKey(siteId),
					}),
					version: null,
				};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Delete the offending key named in the error (AWS console or aws s3 rm)
Keep the Remotion sites bucket dedicated to Remotion; do not store unrelated files in sites/
Use a separate bucket per project to avoid cross-tool key collisions

Example fix

# remove the stray key reported in the error
aws s3 rm s3://<bucketName>/<file.Key>

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await getSites({ region });
} catch (err) {
  if ((err as Error).message.includes('unexpected folder structure')) {
    // parse the bucket/key from the message and delete the stray object, then retry
  }
  throw err;
}

Prevention

Dedicate the Remotion bucket to Remotion only
Never manually upload files into the sites/ prefix
Run getSites periodically to catch pollution early

When it happens

Trigger: Calling getSites when the sites/ prefix contains a key not under a siteId subfolder (e.g. a stray file at sites/stray.json).

Common situations: Manual uploads to the Remotion bucket, another application sharing the bucket, corrupted/orphan keys from interrupted deploys.

Related errors

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