RocketChat/Rocket.Chat · error · Meteor.Error

error-invalid-fields

error-invalid-fields

Error message

Invalid fields parameter provided: "${params.fields}"

What it means

parseJsonQuery handles the deprecated fields projection param only when ALLOW_UNSAFE_QUERY_AND_FIELDS_API_PARAMS=TRUE. The value is parsed with ejson and every entry must be exactly 0 or 1; a parse failure or any other value throws an inner error that is caught, logged, and rethrown as Meteor error-invalid-fields. If the env var is not TRUE the param is ignored entirely — so seeing this error proves the env var is set and the value is malformed.

Source

Thrown at apps/meteor/server/api/lib/parseJsonQuery.ts:80

	let fields: Record<string, 0 | 1> | undefined;
	if (typeof params?.fields === 'string' && isUnsafeQueryParamsAllowed) {
		try {
			apiDeprecationLogger.parameter(route, 'fields', '9.0.0', response, messageGenerator);
			fields = JSON.parse(params.fields) as Record<string, 0 | 1>;
			Object.entries(fields).forEach(([key, value]) => {
				if (value !== 1 && value !== 0) {
					throw new Meteor.Error('error-invalid-sort-parameter', `Invalid fields parameter: ${key}`, {
						helperMethod: 'parseJsonQuery',
					});
				}
			});
		} catch (e) {
			logger.warn({
				msg: 'Invalid fields parameter provided',
				fields: params.fields,
				err: e,
			});
			throw new Meteor.Error('error-invalid-fields', `Invalid fields parameter provided: \"${params.fields}\"`, {
				helperMethod: 'parseJsonQuery',
			});
		}
	}

	// Verify the user's selected fields only contains ones which their role allows
	if (typeof fields === 'object') {
		let nonSelectableFields = Object.keys(API.v1.defaultFieldsToExclude);
		if (isUsersRoute) {
			nonSelectableFields = nonSelectableFields.concat(
				Object.keys(canViewFullOtherUserInfo ? API.v1.limitedUserFieldsToExcludeIfIsPrivilegedUser : API.v1.limitedUserFieldsToExclude),
			);
		}

		Object.keys(fields).forEach((k) => {
			if (nonSelectableFields.includes(k) || nonSelectableFields.includes(k.split(API.v1.fieldSeparator)[0])) {
				fields && delete fields[k as keyof typeof fields];
			}

View on GitHub (pinned to b2c16d5842)

Solutions

  1. Use numeric 0/1 values: fields={"name":1,"emails":0}
  2. Prefer removing the deprecated fields param and relying on the endpoint's default projection
  3. URL-encode the JSON payload to avoid quote corruption

Example fix

// before
GET /api/v1/users.list?fields={"username":true}

// after
GET /api/v1/users.list?fields={"username":1}
Defensive patterns

Strategy: validation

Validate before calling

function buildFieldsParam(fields: Record<string, boolean | 0 | 1>): string | undefined {
  const normalized = Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, v === true ? 1 : v === false ? 0 : v]));
  if (Object.values(normalized).some((v) => v !== 0 && v !== 1)) throw new Error('fields values must be 0 or 1');
  return JSON.stringify(normalized);
}

Type guard

const isFieldsSpec = (v: unknown): v is Record<string, 0 | 1> =>
  typeof v === 'object' && v !== null && !Array.isArray(v) &&
  Object.values(v).every((x) => x === 0 || x === 1);

Try / catch

try {
  await client.get('/api/v1/users.list', { params: { fields: JSON.stringify(fields) } });
} catch (e: any) {
  if (e?.response?.data?.errorType === 'error-invalid-fields') {
    throw new ValidationError('fields param must be JSON with 0/1 values (and requires ALLOW_UNSAFE_QUERY_AND_FIELDS_API_PARAMS=TRUE)');
  }
  throw e;
}

Prevention

When it happens

Trigger: With ALLOW_UNSAFE_QUERY_AND_FIELDS_API_PARAMS=TRUE, sending fields={"name":true}, fields={"name":"1"}, fields=name, or invalid JSON to any parseJsonQuery-backed endpoint.

Common situations: Migrating old SDK usage of the deprecated fields param after enabling the escape hatch; boolean projections copied from other APIs; forgetting that the param is deprecated and scheduled for removal (warned via deprecation headers) in favor of default projections.

Related errors

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