remotion-dev/remotion · error · Error

UnrecognizedClientException: The AWS credentials provided we

Error message

UnrecognizedClientException: The AWS credentials provided were probably mixed up. Learn how to fix this issue here: https://remotion.dev/docs/lambda/troubleshooting/unrecognizedclientexception

What it means

Thrown by renderMediaOnLambda when the underlying Lambda invoke fails with UnrecognizedClientException. AWS throws this exception when credentials are used against the wrong region/partition or when access key and secret are mismatched (e.g., key from one account, secret from another). The library re-throws a friendly message linking the troubleshooting doc.

Source

Thrown at packages/lambda-client/src/render-media-on-lambda.ts:150

			}),
			folderInS3Console: getS3RenderUrl({
				bucketName: res.bucketName,
				renderId: res.renderId,
				region,
			}),
			lambdaInsightsLogs: getLambdaInsightsUrl({
				functionName,
				region,
			}),
			progressJsonInConsole: getProgressJsonUrl({
				bucketName: res.bucketName,
				renderId: res.renderId,
				region,
			}),
		};
	} catch (err) {
		if ((err as Error).stack?.includes('UnrecognizedClientException')) {
			throw new Error(
				'UnrecognizedClientException: The AWS credentials provided were probably mixed up. Learn how to fix this issue here: https://remotion.dev/docs/lambda/troubleshooting/unrecognizedclientexception',
			);
		}

		throw err;
	}
};

export const renderMediaOnLambdaOptionalToRequired = (
	options: RenderMediaOnLambdaInput,
): InnerRenderMediaOnLambdaInput => {
	return {
		offthreadVideoThreads: options.offthreadVideoThreads ?? null,
		audioBitrate: options.audioBitrate ?? null,
		audioCodec: options.audioCodec ?? null,
		chromiumOptions: options.chromiumOptions ?? {},
		codec: options.codec,
		colorSpace: options.colorSpace ?? null,

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Re-set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as a matched pair from the same IAM user.
Ensure AWS_REGION matches the region where the Remotion Lambda function is deployed.
Verify with `aws sts get-caller-identity` that the active credentials resolve to the expected account.
If using profiles, confirm AWS_PROFILE points to the same profile used for deployFunction.
See https://remotion.dev/docs/lambda/troubleshooting/unrecognizedclientexception

Example fix

// before (mismatched creds / region)
// AWS_ACCESS_KEY_ID=AKIA...accountA
// AWS_SECRET_ACCESS_KEY=...accountB
// AWS_REGION=eu-west-1  (function deployed in us-east-1)

// after
// AWS_ACCESS_KEY_ID=AKIA...accountA
// AWS_SECRET_ACCESS_KEY=...accountA  (matched pair)
// AWS_REGION=us-east-1

Defensive patterns

Strategy: validation

Validate before calling

// Verify the credentials resolve to the expected account before rendering
const sts = new STSClient({ region });
const id = await sts.send(new GetCallerIdentityCommand({}));
if (id.Account !== EXPECTED_ACCOUNT_ID) {
  throw new Error('Active credentials do not match expected account; refusing to render');
}

Try / catch

try {
  await renderMediaOnLambda(opts);
} catch (e) {
  if (e instanceof Error && /UnrecognizedClientException/.test(e.message)) {
    // halt and surface a credentials-config error; do NOT retry
    throw new Error('AWS credentials misconfigured — check key/secret/region');
  }
  throw e;
}

Prevention

Always set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as a matched pair.
Confirm AWS_REGION matches the function's deployment region.
Run aws sts get-caller-identity in CI before invoking Lambda.

When it happens

Trigger: The wrapped render call catches an error whose stack includes 'UnrecognizedClientException' and replaces it with this message + the docs URL.

Common situations: Mixing AWS_ACCESS_KEY_ID from one account with AWS_SECRET_ACCESS_KEY from another in .env; setting AWS_REGION to a region different from where the Lambda was deployed; copying only the access key without the secret after rotation; profile mismatch between deploy and render machines.

Related errors

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