RocketChat/Rocket.Chat · error · Error

error-invalid-characters-in-file-name

error-invalid-characters-in-file-name

Error message

error-invalid-characters-in-file-name

What it means

Final branch of sanitizeFileName (sanitizeFileName.ts:14-16): the (separator-free) name must match /^[a-zA-Z0-9._-]+$/ or it is rejected with error-invalid-characters-in-file-name. Allowed: ASCII letters, digits, dot, underscore, hyphen. Anything else - spaces, unicode letters, '$', '#', parentheses, backslashes - fails. The FileSystem store applies this on every write/read/stat/unlink.

Source

Thrown at apps/meteor/server/lib/media/file/functions/sanitizeFileName.ts:15

import path from 'node:path';

export function sanitizeFileName(fileName: string) {
	const base = path.basename(fileName);

	if (base !== fileName) {
		throw new Error('error-invalid-file-name');
	}

	if (base === '.' || base.startsWith('..')) {
		throw new Error('error-invalid-file-name');
	}

	if (!/^[a-zA-Z0-9._-]+$/.test(base)) {
		throw new Error('error-invalid-characters-in-file-name');
	}

	return base;
}

View on GitHub (pinned to b2c16d5842)

Solutions

1. Sanitize names before upload: strip/replace characters outside [a-zA-Z0-9._-] (e.g. replace with '-')
2. For legacy records failing on access, rewrite the stored file name in the Uploads/FileStore data to a conforming one (and rename on disk)
3. Route uploads through Rocket.Chat's own upload flow, which sanitizes the name client-side
4. Add a client-side regex pre-check identical to the server's to give immediate feedback

Example fix

// before: uploading 'relatório final (v2).pdf' -> error-invalid-characters-in-file-name
// after
const safe = file.name.replace(/[^a-zA-Z0-9._-]/g, '-').replace(/^\.+/g, '');
uploadWithSafeName(file, safe);

const FILE_NAME_RE = /^[a-zA-Z0-9._-]+$/;
export const sanitizeName = (name: string): string =>
  path.basename(name).replace(/[^a-zA-Z0-9._-]/g, '-').replace(/^\.+/g, '') || 'file';

if (!FILE_NAME_RE.test(name)) name = sanitizeName(name);

const isSafeStoreFileName = (name: string): name is string =>
  /^[a-zA-Z0-9._-]+$/.test(name) && name !== '.' && !name.startsWith('..');

try {
  store.createWriteStream({ name, ... });
} catch (error: any) {
  if (error.message === 'error-invalid-characters-in-file-name') {
    return retryWith(path.basename(name).replace(/[^a-zA-Z0-9._-]/g, '-'));
  }
  throw error;
}

When it happens

Trigger: File names with spaces ('my sound.mp3'), special characters ('sound$.mp3', 'file(1).pdf'), unicode/emoji names, or Windows backslash names ('..\\passwd') reaching a FileSystem store operation because the caller bypassed the normal client-side name sanitization.

Common situations: Upgrades that hardened name rules: uploads stored before the guard now fail on download with legacy names; custom REST scripts and apps-engine apps writing raw names; assets (sounds, emojis) installed with human-readable names containing spaces; non-English file names with accented characters.

Related errors

• error-invalid-file-name
• error-invalid-data
• error-not-allowed
• error-invalid-file
• error-invalid-user

AI-assisted analysis of RocketChat/Rocket.Chat@b2c16d5842 (2026-08-18). Data as JSON: /api/errors/d7dd11d2a127e378. Report an issue: GitHub.