mongodb/node-mongodb-native · error · MongoParseError

Option pkFactory must be an object with a createPk…

Error message

Option pkFactory must be an object with a createPk function, got ${value}

What it means

`pkFactory` lets you override _id generation. The transform at src/connection_string.ts:954 requires the value to be a record containing a `createPk` member that is a function (validated by `isRecord(value, ['createPk']) && typeof value.createPk === 'function'`); otherwise MongoParseError is thrown at src/connection_string.ts:958. The default factory is DEFAULT_PK_FACTORY (ObjectID-based).

Solutions

Wrap the generator: `pkFactory: { createPk: () => uuid() }`.
Ensure the returned value is a BSON-serializable type (e.g. UUID, ObjectId, string).
If you only want ObjectIds, omit pkFactory entirely to use the default.

Example fix

// before
new MongoClient(uri, { pkFactory: () => crypto.randomUUID() });

// after
new MongoClient(uri, { pkFactory: { createPk: () => crypto.randomUUID() } });

Defensive patterns

Strategy: type-guard

Validate before calling

function isPkFactory(v: unknown): v is { createPk: () => unknown } {
  return typeof v === 'object' && v !== null && typeof (v as any).createPk === 'function';
}
if (opts.pkFactory != null && !isPkFactory(opts.pkFactory)) {
  throw new Error('pkFactory must be { createPk: function }');
}

Type guard

function isPkFactory(v: unknown): v is { createPk: () => unknown } { return !!v && typeof v === 'object' && typeof (v as any).createPk === 'function'; }

Try / catch

try { client = new MongoClient(uri, opts); } catch (e) { if (e instanceof MongoParseError && /pkFactory/.test(e.message)) { opts.pkFactory = { createPk: (opts as any).pkFactory }; client = new MongoClient(uri, opts); } else throw e; }

Prevention

Always wrap generator functions in `{ createPk: fn }`.
Make the createPk return value BSON-serializable.
Omit pkFactory entirely if you want default ObjectId generation.

When it happens

Trigger: Passing a bare function `pkFactory: () => uuid()`; passing a class constructor; passing `{ generate: fn }` (wrong key); passing `{ createPk: 'not a function' }`.

Common situations: Adapting examples from other drivers or ODMs that take a function directly; renaming the method without updating the option; providing a UUID v4 function but forgetting to wrap it.

Related errors

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

Appendix: source

Thrown at src/connection_string.ts:958

    type: 'boolean'
  },
  name: {
    target: 'driverInfo',
    transform({ values: [value], options }) {
      return { ...options.driverInfo, name: String(value) };
    }
  } as OptionDescriptor,
  noDelay: {
    default: true,
    type: 'boolean'
  },
  pkFactory: {
    default: DEFAULT_PK_FACTORY,
    transform({ values: [value] }): PkFactory {
      if (isRecord(value, ['createPk'] as const) && typeof value.createPk === 'function') {
        return value as PkFactory;
      }
      throw new MongoParseError(
        `Option pkFactory must be an object with a createPk function, got ${value}`
      );
    }
  },
  promoteBuffers: {
    type: 'boolean'
  },
  promoteLongs: {
    type: 'boolean'
  },
  promoteValues: {
    type: 'boolean'
  },
  useBigInt64: {
    type: 'boolean'
  },
  proxyHost: {
    type: 'string'

View on GitHub (pinned to dce7939f86)