remotion-dev/remotion · error · TypeError

The "filename" must be a string, but you passed a value of t

Error message

The "filename" must be a string, but you passed a value of type ${typeof filename}

What it means

When you register a render artifact (a custom output file emitted alongside the render via the artifacts API), the `filename` field must be a string so it can be written to the output directory and matched against the asset manifest. validateArtifactFilename rejects non-string filenames before they reach the filesystem layer.

Source

Thrown at packages/core/src/validation/validate-artifact.ts:5

import type {TRenderAsset} from '../CompositionManager';

export const validateArtifactFilename = (filename: unknown) => {
	if (typeof filename !== 'string') {
		throw new TypeError(
			`The "filename" must be a string, but you passed a value of type ${typeof filename}`,
		);
	}

	if (filename.trim() === '') {
		throw new Error('The `filename` must not be empty');
	}

	if (!filename.match(/^([0-9a-zA-Z-!_.*'()/:&$@=;+,?]+)/g)) {
		throw new Error(
			'The `filename` must match "/^([0-9a-zA-Z-!_.*\'()/:&$@=;+,?]+)/g". Use forward slashes only, even on Windows.',
		);
	}
};

const validateContent = (content: unknown) => {
	if (typeof content !== 'string' && !(content instanceof Uint8Array)) {
		throw new TypeError(

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Pass filename as a string literal: {filename: 'output.txt', content: '...'}.
2. If the value is computed, coerce explicitly: {filename: String(name), content: '...'}.
3. If the value is a path object, extract its string form first (e.g. path.join(...) or obj.toString()).

Example fix

// before
registerRenderAsset({type: 'artifact', filename: 123, content: 'data'});
// after
registerRenderAsset({type: 'artifact', filename: 'output-123.txt', content: 'data'});

if (typeof filename !== 'string') {
  throw new Error(`filename must be string, got ${typeof filename}`);
}

const isFilenameString = (v: unknown): v is string =>
  typeof v === 'string';

When it happens

Trigger: Registering an artifact with a non-string filename, e.g. {filename: 123, content: '...'} or {filename: {path: 'x.txt'}, content: '...'}, via registerRenderAsset or the artifacts registration API consumed by validateRenderAsset.

Common situations: Constructing the filename dynamically from a number without String(); spreading an untyped API response into the artifact object; passing a path object instead of a string.

Related errors

• The `filename` must not be empty
• The `filename` must match "/^([0-9a-zA-Z-!_.*'()/:&$@=;+,?]+
• No src passed
• The label parameter of delayRender() must be a string or und
• The continueRender() method must be called with a parameter

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