mongodb/node-mongodb-native · error · MongoRuntimeError

unexpected readPreference=${mode} (should never happen). Pl

Error message

unexpected readPreference=${mode} (should never happen).  Please report a bug in the Node driver Jira project.

What it means

The `default` branch of the read-preference switch in `secondarySelector`, guarded by a TypeScript `never` exhaustive check on `mode` (server_selection.ts:369). It can only fire if a read preference mode outside the five known values reaches selection — i.e. the type system was bypassed. The message explicitly asks for a bug report.

Source

Thrown at src/sdam/server_selection.ts:371

        // unlike readPreference=primary, here we do filter for deprioritized servers.
        // if the primary is deprioritized, deprioritized secondaries take precedence.
        const eligiblePrimary = primary.filter(isDeprioritizedFactory(deprioritized));
        if (eligiblePrimary.length) return eligiblePrimary;

        // we have no eligible primary nor secondaries that have not been deprioritized
        return secondaries.length
          ? latencyWindowReducer(topologyDescription, secondaries)
          : primary;
      }

      // return all secondaries in the latency window.
      return latencyWindowReducer(topologyDescription, secondaries);
    }

    default: {
      const _exhaustiveCheck: never = mode;
      throw new MongoRuntimeError(
        `unexpected readPreference=${mode} (should never happen).  Please report a bug in the Node driver Jira project.`
      );
    }
  }
}

/**
 * Returns a function which selects servers based on a provided read preference
 *
 * @param readPreference - The read preference to select with
 */
export function readPreferenceServerSelector(readPreference: ReadPreference): ServerSelector {
  if (!readPreference.isValid()) {
    throw new MongoInvalidArgumentError('Invalid read preference specified');
  }

  return function readPreferenceServers(
    topologyDescription: TopologyDescription,

View on GitHub (pinned to 3366c21a63)

Solutions

1. Stop passing non-standard mode strings; use only the five documented modes.
2. Audit any code that casts or constructs ReadPreference with `as`.
3. Report a bug with the driver version and the offending mode value if it occurs with normal usage.

Example fix

// before
new ReadPreference('fastest' as ReadPreferenceMode);
// after
new ReadPreference('nearest');

const MODES = ['primary','primaryPreferred','secondary','secondaryPreferred','nearest'];
function readPref(mode) {
  if (!MODES.includes(mode)) throw new TypeError('Unknown read preference mode: ' + mode);
  return new ReadPreference(mode);
}

function isKnownMode(mode) {
  return ['primary','primaryPreferred','secondary','secondaryPreferred','nearest'].includes(mode);
}

When it happens

Trigger: A custom/monkeypatched ReadPreference carrying an unknown mode string cast through `as ReadPreferenceMode`; an internal corruption of the mode field; using a future driver feature with an outdated type declaration.

Common situations: Casting an arbitrary string to the mode type; monkeypatching internals; an incompatible fork of the driver.

Related errors

• client.connect did not create a topology but also did not th
• unexpected topology type: ${topologyDescription.type} (this
• Unexpected null serverSession for an explicit session
• Operation passed in cannot be an Array
• Operation passed in cannot be an Array

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