remotion-dev/remotion · error · TypeError

A custom role ARN must either be "undefined" or a string, bu

Error message

A custom role ARN must either be "undefined" or a string, but instead got: ${JSON.stringify(customRoleArn)}

What it means

Thrown by validateCustomRoleArn() (a TypeError) when customRoleArn is neither undefined nor a string. Used by deployFunction() and the `functions deploy` CLI to gate the optional IAM execution-role override.

Source

Thrown at packages/lambda/src/shared/validate-custom-role-arn.ts:6

export const validateCustomRoleArn = (customRoleArn: unknown) => {
	if (
		typeof customRoleArn !== 'undefined' &&
		typeof customRoleArn !== 'string'
	) {
		throw new TypeError(
			'A custom role ARN must either be "undefined" or a string, but instead got: ' +
				JSON.stringify(customRoleArn),
		);
	}
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Pass either a role ARN string (arn:aws:iam::<account>:role/<name>) or omit it / set to undefined.
Coerce or validate the value to string|undefined before calling deployFunction.
Use the TypeScript type (customRoleArn?: string) so the compiler catches mismatches.

Example fix

// before
deployFunction({region, customRoleArn: config.roleArn /* number? */})
// after
const customRoleArn = typeof config.roleArn === 'string' ? config.roleArn : undefined
deployFunction({region, customRoleArn})

Defensive patterns

Strategy: type-guard

Validate before calling

if (customRoleArn !== undefined && typeof customRoleArn !== 'string') {
  throw new TypeError('customRoleArn must be undefined or a string')
}

Type guard

const isValidCustomRoleArn = (v: unknown): v is string | undefined =>
  v === undefined || typeof v === 'string'

Prevention

Type config fields explicitly as string | undefined.
When reading from env, coerce with a helper that returns string | undefined.
Validate role ARN shape (arn:aws:iam::...) in addition to type.

When it happens

Trigger: Passing deployFunction({customRoleArn: ...}) with a number, boolean, object, or array instead of an ARN string or undefined.

Common situations: Reading customRoleArn from env/config without coercion; spreading a config object whose value is the wrong type; deserialised JSON where the field became a non-string.

Related errors

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