remotion-dev/remotion · error · Error

The `filename` must match "/^([0-9a-zA-Z-!_.*'()/:&$@=;+,?]+

Error message

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

What it means

validateArtifactFilename enforces that the filename only contains characters in the set [0-9a-zA-Z-!_.*'()/:&$@=;+,?] and uses forward slashes for path separation. Backslashes, spaces, angle brackets, and most punctuation are rejected to keep filenames portable across operating systems and safe for the render manifest. The check exists because Windows backslashes and spaces commonly break render pipelines.

Source

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

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');
	}
};

export const validateRenderAsset = (artifact: TRenderAsset) => {

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Replace backslashes with forward slashes: filename = filename.replace(/\\/g, '/').
2. Remove or replace spaces and disallowed characters: use hyphens or underscores instead.
3. Construct paths with forward slashes explicitly, e.g. 'subdir/output.json'.
4. If you need a space or special char in the displayed name, encode it in the content/metadata instead of the filename.

Example fix

// before (on Windows)
const filename = path.join('subdir', 'my file.txt'); // 'subdir\\my file.txt'
registerRenderAsset({type: 'artifact', filename, content});
// after
const filename = 'subdir/my-file.txt';
registerRenderAsset({type: 'artifact', filename, content});

const ALLOWED = /^[0-9a-zA-Z\-!_.*'()\/:&$@=;+,?]+$/;
if (typeof filename !== 'string' || !ALLOWED.test(filename)) {
  throw new Error('filename contains disallowed characters; use forward slashes');
}

const ARTIFACT_FILENAME_RE = /^[0-9a-zA-Z\-!_.*'()\/:&$@=;+,?]+$/;
const isValidArtifactFilename = (v: unknown): v is string =>
  typeof v === 'string' &&
  v.trim().length > 0 &&
  ARTIFACT_FILENAME_RE.test(v);

When it happens

Trigger: Registering an artifact whose filename contains a backslash (filename='dir\\file.txt'), a space (filename='my file.txt'), or any character outside the allowed set such as <, >, |, ", #, %, ^, ~, [, ], {, }, `.

Common situations: Using path.join on Windows which produces backslashes; copying a filename with spaces from an OS file dialog; embedding query-string characters like # or % that are not in the allowed set.

Related errors

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