RocketChat/Rocket.Chat · critical · Error

Invalid MONGO_OPTIONS environment variable: must be valid JS

Error message

Invalid MONGO_OPTIONS environment variable: must be valid JSON.

What it means

The rocketchat-mongo-config Meteor package reads process.env.MONGO_OPTIONS, JSON.parses it, and Object.assigns the result into the Mongo connection options before calling Mongo.setConnectionOptions. If the variable is set but is not valid JSON, package startup throws this error immediately, chaining the JSON parse error as cause — the app fails to boot.

Source

Thrown at apps/meteor/packages/rocketchat-mongo-config/server/index.js:32

// This is fixed in Node 10, but this supports LTS versions
tls.DEFAULT_ECDH_CURVE = 'auto';

const mongoConnectionOptions = {
	// add retryWrites=false if not present in MONGO_URL
	...(!process.env.MONGO_URL.includes('retryWrites') && { retryWrites: false }),
	ignoreUndefined: false,

	// TODO ideally we should call isTracingEnabled(), but since this is a Meteor package we can't :/
	monitorCommands: ['yes', 'true'].includes(String(process.env.TRACING_ENABLED).toLowerCase()),
};

const mongoOptionStr = process.env.MONGO_OPTIONS;
if (typeof mongoOptionStr !== 'undefined') {
	try {
		const mongoOptions = JSON.parse(mongoOptionStr);
		Object.assign(mongoConnectionOptions, mongoOptions);
	} catch (error) {
		throw new Error('Invalid MONGO_OPTIONS environment variable: must be valid JSON.', { cause: error });
	}
}

if (Object.keys(mongoConnectionOptions).length > 0) {
	Mongo.setConnectionOptions(mongoConnectionOptions);
}

process.env.HTTP_FORWARDED_COUNT = process.env.HTTP_FORWARDED_COUNT || '1';

// Just print to logs if in TEST_MODE due to a bug in Meteor 2.5: TypeError: Cannot read property '_syncSendMail' of null
if ((process.env.TEST_MODE === 'true' || process.env.TEST_MODE === 'api')) {
	Email.sendAsync = async function _sendAsync(options) {
		console.log('Email.sendAsync', options);
	};
} else if (process.env.NODE_ENV !== 'development') {
	// Send emails to a "fake" stream instead of print them in console in case MAIL_URL or SMTP is not configured
	const stream = new PassThrough();
	stream.on('data', () => {});

View on GitHub (pinned to b2c16d5842)

Solutions

1. Set the variable to strict JSON, e.g. MONGO_OPTIONS='{"ssl":true,"sslValidate":false}'.
2. Validate before deploy: node -e 'JSON.parse(process.argv[1])' "$MONGO_OPTIONS".
3. Unset MONGO_OPTIONS entirely if no extra connection options are needed.

Example fix

# before
export MONGO_OPTIONS="ssl=true&sslValidate=false"

# after
export MONGO_OPTIONS='{"ssl":true,"sslValidate":false}'

// startup/CI guard before launching the app
if (process.env.MONGO_OPTIONS) {
	try {
		JSON.parse(process.env.MONGO_OPTIONS);
	} catch (e) {
		console.error('MONGO_OPTIONS must be valid JSON, e.g. \'{"ssl":true}\'');
		process.exit(1);
	}
}

function isValidMongoOptionsEnv(value: string | undefined): boolean {
	if (value === undefined) return true;
	try {
		const parsed = JSON.parse(value);
		return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed);
	} catch {
		return false;
	}
}

When it happens

Trigger: Starting apps/meteor with MONGO_OPTIONS in a non-JSON format: key=value strings like 'ssl=true', Mongo URI query syntax 'ssl=true&sslValidate=false', single-quoted pseudo-JSON, trailing commas, or unquoted keys.

Common situations: Operators copying options syntax from MONGO_URL documentation into MONGO_OPTIONS; docker-compose/Kubernetes YAML quoting that mangles the value; stray whitespace/BOM in .env files.

Related errors

• Error dropping redundant indexes, continuing...
• Not migrating, control is locked. Will retry.
• SAML Provider not loaded due to invalid configuration
• Invalid settings found on DB. Deleting them.
• apps-engine-not-loaded

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