remotion-dev/remotion · error · Error

The `filename` must not be empty

Error message

The `filename` must not be empty

What it means

After confirming the artifact filename is a string, validateArtifactFilename rejects empty or whitespace-only filenames because they cannot identify a file in the output directory and would collide or be silently dropped by the filesystem.

Source

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

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(
			`The "content" must be a string or Uint8Array, but you passed a value of type ${typeof content}`,
		);
	}

	if (typeof content === 'string' && content.trim() === '') {
		throw new Error('The `content` must not be empty');

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Provide a non-empty, meaningful filename: {filename: 'report.json', content: '...'}.
2. If the filename is built dynamically, fall back to a default when empty: filename = name || 'artifact.bin'.
3. Validate the generated filename is non-empty after trim() before registering the artifact.

Example fix

// before
const filename = `${prefix}-${suffix}`; // both undefined -> '-'
registerRenderAsset({type: 'artifact', filename: filename.trim(), content});
// after
const filename = `${prefix ?? 'artifact'}-${suffix ?? Date.now()}.bin`;
registerRenderAsset({type: 'artifact', filename, content});

if (typeof filename !== 'string' || filename.trim() === '') {
  throw new Error('filename must be a non-empty string');
}

const isNonEmptyFilename = (v: unknown): v is string =>
  typeof v === 'string' && v.trim().length > 0;

When it happens

Trigger: Registering an artifact with filename="", filename=" ", or a value that becomes empty after trim() (e.g. a template literal that resolves to only spaces).

Common situations: Building a filename from optional fields that are all undefined, producing an empty string; trimming user input that turns out to be blank; a default value of '' used before a real name is assigned.

Related errors

• The "filename" must be a string, but you passed a value of t
• 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/7a1bdf664b5e5c7e. Report an issue: GitHub.