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

Same UnrecognizedClientException guard as in renderMediaOnLambda, but applied to renderStillOnLambda. The Lambda invoke for the still render fails because the AWS credentials cannot be recognized (wrong region/partition or mismatched key/secret). The library re-throws with the docs link.

Source

Thrown at packages/lambda-client/src/render-still-on-lambda.ts:149

		return {
			estimatedPrice: res.estimatedPrice,
			url: res.output,
			outKey: res.outKey,
			sizeInBytes: res.size,
			bucketName: res.bucketName,
			renderId: res.renderId,
			cloudWatchLogs: getCloudwatchMethodUrl({
				functionName,
				method: ServerlessRoutines.still,
				region,
				renderId: res.renderId,
				rendererFunctionName: null,
			}),
			artifacts: res.receivedArtifacts,
		};
	} 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 internalRenderStillOnLambda = wrapWithErrorHandling(
	innerRenderStillOnLambda,
);

/*
 * @description Renders a still image inside a lambda function and writes it to the specified output location.
 * @see [Documentation](https://remotion.dev/docs/lambda/renderstillonlambda)
 */
export function renderStillOnLambda(
	input: RenderStillOnLambdaInput & {

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 deployment region of the Lambda function.
Run aws sts get-caller-identity to confirm the active principal.
See https://remotion.dev/docs/lambda/troubleshooting/unrecognizedclientexception

Example fix

// before
await renderStillOnLambda({ ...params }); // fails: mismatched creds

// after — set matched credentials and correct region
process.env.AWS_REGION = 'us-east-1';
await renderStillOnLambda({ ...params });

Defensive patterns

Strategy: validation

Validate before calling

// Same credential sanity check as the media render path
const id = await new STSClient({ region }).send(new GetCallerIdentityCommand({}));
if (id.Account !== EXPECTED_ACCOUNT_ID) {
  throw new Error('Credentials do not match expected account; aborting still render');
}

Try / catch

try {
  await renderStillOnLambda(opts);
} catch (e) {
  if (e instanceof Error && /UnrecognizedClientException/.test(e.message)) {
    throw new Error('AWS credentials misconfigured — check key/secret/region');
  }
  throw e;
}

Prevention

Use the same matched credential pair for still and video renders.
Confirm AWS_REGION before invoking.
Run aws sts get-caller-identity in CI before the first render.

When it happens

Trigger: The wrapped renderStill call catches an error whose stack includes 'UnrecognizedClientException'.

Common situations: Same credential/region mismatches as renderMediaOnLambda, encountered on the still-render path; rotating credentials and updating only the access key; using a different AWS profile for stills vs. video renders.

Related errors

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