mongodb/node-mongodb-native · info · MongoParseError

Descriptors missing a type must define a transform

Error message

Descriptors missing a type must define a transform

What it means

Internal invariant violation in the driver's option-processing engine. The OPTIONS descriptor table routes each option through a switch on its declared `type`; the default branch (src/connection_string.ts:624-631) runs only when no recognized `type` is set, and it requires a `transform` function. This error means a descriptor has neither a known `type` nor a `transform`, which is impossible for any built-in option. End users cannot trigger it through normal MongoClientOptions.

Source

Thrown at src/connection_string.ts:626

        break;
      }
      // The value should always be a string here, but since the array is typed as unknown
      // there still needs to be an explicit cast.
      // eslint-disable-next-line @typescript-eslint/no-base-to-string
      mongoOptions[name] = String(values[0]);
      break;
    case 'record':
      if (!isRecord(values[0])) {
        throw new MongoParseError(`${name} must be an object`);
      }
      mongoOptions[name] = values[0];
      break;
    case 'any':
      mongoOptions[name] = values[0];
      break;
    default: {
      if (!transform) {
        throw new MongoParseError('Descriptors missing a type must define a transform');
      }
      const transformValue = transform({ name, options: mongoOptions, values });
      mongoOptions[name] = transformValue;
      break;
    }
  }
}

interface OptionDescriptor {
  target?: string;
  type?: 'boolean' | 'int' | 'uint' | 'record' | 'string' | 'any';
  default?: any;

  deprecated?: boolean | string;
  /**
   * @param name - the original option name
   * @param options - the options so far for resolution
   * @param values - the possible values in precedence order

View on GitHub (pinned to 3366c21a63)

Solutions

1. Ensure any custom option descriptor sets a valid `type` ('boolean'|'int'|'uint'|'record'|'string'|'any') or supplies a `transform` function
2. If you are not intentionally extending OPTIONS, file a driver bug with the option name and full stack trace
3. Stop monkey-patching the exported OPTIONS object; pass options through the documented MongoClientOptions API

Example fix

// before (broken descriptor)
OPTIONS.myOpt = { default: 1 };
// after
OPTIONS.myOpt = { type: 'uint', default: 1 };
// or supply a transform
OPTIONS.myOpt = {
  transform({ values: [v] }) {
    return Number(v);
  }
};

// Internal invariant: verify any descriptor you add to OPTIONS
import { OPTIONS } from 'mongodb'; // illustrative; OPTIONS is internal
function assertDescriptorValid(name, d) {
  const validTypes = ['boolean','int','uint','record','string','any'];
  if (!d) throw new Error(`Missing descriptor for ${name}`);
  if (!validTypes.includes(d.type) && typeof d.transform !== 'function') {
    throw new Error(`Descriptor ${name} needs a type or transform`);
  }
}

function isValidOptionDescriptor(d) {
  if (!d || typeof d !== 'object') return false;
  const validTypes = ['boolean','int','uint','record','string','any'];
  return validTypes.includes(d.type) || typeof d.transform === 'function';
}

When it happens

Trigger: Mutating or extending the exported `OPTIONS` object (src/connection_string.ts:649) with a descriptor that omits both `type` and `transform`; a bug in a forked or patched driver version; monkey-patching OPTIONS at runtime. Not reachable from `new MongoClient(uri, options)` with documented options.

Common situations: Driver/library developers editing option descriptors; code that spreads custom descriptors into OPTIONS; using an experimental driver branch with incomplete descriptors.

Related errors

• No workflow provided to the OIDC auth provider.
• ${name} must be an object with 'username' and 'password' pro
• authMechanism one of ${mechanisms}, got ${value}
• Invalid `serverApi` property; must specify a version from th
• Invalid server API version=${versionToValidate}; must be in

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/5e0238590ba4939b.json. Report an issue: GitHub.