mongodb/node-mongodb-native · error · MongoParseError

Descriptors missing a type must define a transform

Error message

Descriptors missing a type must define a transform

What it means

Thrown by MongoParseError at src/connection_string.ts:626 in the `default` arm of `setOption` when an option descriptor has neither a known `type` nor a `transform`. This is an internal-driver invariant: every entry in the OPTIONS table must declare a type or a transform. End users should normally never see it; it indicates a bug in the driver's OPTIONS registry.

Solutions

1. If you maintain a fork, ensure every OPTIONS entry declares either `type` (one of boolean/int/uint/record/string/any) or a `transform` function.
2. If you are an end user, report this as a driver bug — no URI or options combination should trigger it on an official release.
3. Pin to a known-good driver version while the issue is investigated.

try { new MongoClient(uri, options); } catch (e) { if (e instanceof MongoParseError && /Descriptors missing a type must define a transform/.test(e.message)) { console.error('Driver internal error — please report. Option registry is malformed.'); } else throw e; }

When it happens

Trigger: Only reachable if someone modifies the OPTIONS object in src/connection_string.ts to add a descriptor with neither `type` nor `transform`. Triggered then by the driver attempting to apply that option.

Common situations: Forking the driver and adding an option incorrectly; running against an unreleased/patched driver version with an OPTIONS typo.

Related errors

• authMechanism one of
• Invalid server API version=
• Invalid `serverApi` property; must specify a version from…
• must be an object
• No workflow provided to the OIDC auth provider.

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/5e0238590ba4939b. Report an issue: GitHub.

Appendix: 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 dce7939f86)