Output file "${params.key}" in bucket "${params.bucketName}"

Error message

Output file "${params.key}" in bucket "${params.bucketName}" already exists. Delete it before re-rendering, or set the 'overwrite' option in renderMediaOnLambda() to overwrite it.

What it means

This error is thrown by writeFileWithRetries when an S3 upload with the ifNotExists (conditional) option fails with HTTP status 412 Precondition Failed, meaning an object already exists at the destination key. Remotion Lambda refuses to silently overwrite existing render outputs, so the render fails fast. The original upload error is attached as `cause`.

Source

Thrown at packages/lambda-client/src/write-file.ts:127

	}
};

const writeFileWithRetries = async (
	params: WriteFileInput<AwsProvider> & {
		retries?: number;
		ifNotExists: boolean;
	},
): Promise<void> => {
	const remainingRetries = params.retries ?? 2;
	try {
		await tryLambdaWriteFile(params);
	} catch (err) {
		if (
			params.ifNotExists &&
			(err as {$metadata: {httpStatusCode: number} | undefined}).$metadata
				?.httpStatusCode === 412
		) {
			throw new Error(
				`Output file "${params.key}" in bucket "${params.bucketName}" already exists. Delete it before re-rendering, or set the 'overwrite' option in renderMediaOnLambda() to overwrite it.`,
				{cause: err},
			);
		}

		// A failed upload may have consumed a Readable, and we cannot recreate it here.
		// Retrying it could upload an empty body and mask the original error.
		const bodyCanBeRetried =
			typeof params.body === 'string' || params.body instanceof Uint8Array;
		if (remainingRetries === 0 || !bodyCanBeRetried) {
			throw err;
		}

		const backoff = 2 ** (2 - remainingRetries) * 2000;
		await new Promise((resolve) => {
			setTimeout(resolve, backoff);
		});

View on GitHub (pinned to b2f4e34732)

Solutions

Delete the existing object from the S3 bucket (console, aws s3 rm, or DeleteObject) before rendering again
Pass overwrite: true to renderMediaOnLambda() so the existing object is replaced
Use a unique output key per render (e.g. include the render id or timestamp) instead of a fixed key
Catch this error and redirect output to a different key

Example fix

// before
await renderMediaOnLambda({
  composition: 'MyComp',
  serveUrl: bundleUrl,
  codec: 'h264',
  inputProps: {},
  downloadName: 'out/video.mp4',
});
// after
await renderMediaOnLambda({
  composition: 'MyComp',
  serveUrl: bundleUrl,
  codec: 'h264',
  inputProps: {},
  downloadName: 'out/video.mp4',
  overwrite: true,
});

Defensive patterns

Strategy: try-catch

Validate before calling

import {getRenderProgress} from '@remotion/lambda-client';
import {HeadObjectCommand, S3Client} from '@aws-sdk/client-s3';
const s3 = new S3Client({});
async function outputExists(bucket: string, key: string) {
  try {
    await s3.send(new HeadObjectCommand({Bucket: bucket, Key: key}));
    return true;
  } catch {
    return false;
  }
}

Type guard

const isOutputAlreadyExists = (e: unknown): e is Error & {cause: {$metadata?: {httpStatusCode?: number}}} => e instanceof Error && (e as {cause?: {$metadata?: {httpStatusCode?: number}}}).cause?.$metadata?.httpStatusCode === 412;

Try / catch

try {
  await renderMediaOnLambda(params);
} catch (err) {
  if (String(err).includes('already exists')) {
    await renderMediaOnLambda({...params, overwrite: true});
  } else {
    throw err;
  }
}

Prevention

Pass overwrite: true when re-rendering to a fixed key
Derive output keys from the render id or a timestamp so they are unique per run
Head-check the S3 key before rendering when you need to detect leftovers
Clean up stale outputs from failed renders before retrying

When it happens

Trigger: Calling renderMediaOnLambda() (or the internal lambdaWriteFileIfNotExists path) with an output key whose object already exists in the bucket, while the overwrite/ifNotExists behavior is active, so S3 returns 412 and this error replaces it.

Common situations: Re-rendering to the same output key after a previous render; a prior failed/partial render left the file behind; reusing a fixed key across runs instead of a unique render id; forgetting to pass overwrite: true.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

AI-assisted analysis of remotion-dev/remotion@b2f4e34732 (2026-09-09). Data as JSON: /api/errors/e97f0fee1f8546dc. Report an issue: GitHub.