mongodb/node-mongodb-native · error · MongoRuntimeError

An unexpected error type

Error message

An unexpected error type: ${typeof error}

What it means

Thrown by Server.decorateCommandError() (src/sdam/server.ts:457) as MongoRuntimeError when the error passed in is not an object, is null, or lacks a 'name' property — i.e. an error value that violates the expected Error shape. This is an internal invariant: the driver expects any caught failure to be an Error-like object. Encountering it usually indicates a bug in the driver, a thrown primitive, or an unusual runtime/host environment.

Solutions

1. Report the issue to the driver maintainers with a reproduction; this is typically not caller-fixable.
2. Ensure any custom auth/compression plugins throw real Error objects.
3. Upgrade the driver and native bindings to the latest versions.
4. Wrap throw sites in your own code to emit Error instances.

function isErrorLike(v): v is Error {
  return v != null && typeof v === 'object' && 'name' in v;
}

try {
  await collection.findOne({});
} catch (e) {
  if (e instanceof MongoRuntimeError && /unexpected error type/.test(e.message)) {
    // log full context; this is likely a driver/native bug
  }
  throw e;
}

When it happens

Trigger: A connection or wire-protocol handler receives a thrown string, number, or null instead of an Error object — possible from native bindings, a misbehaving custom auth plugin, or a driver bug.

Common situations: Native module (kerberos, zstd, client-encryption) throwing a non-Error value, Promise rejection with a primitive, or driver internals mishandling an edge case.

Related errors

• A collection name must be determined before getMore
• A collection name must be determined before killCursors
• Attempted to get a refresh token when none exists.
• Attempted to get an access token when none exists.
• Attempted to get IDP information when none exists.

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

Appendix: source

Thrown at src/sdam/server.ts:457

        markServerUnknown(this, error);
      } else if (connection) {
        this.pool.clear({ serviceId: connection.serviceId });
      }
    }
  }

  /**
   * Ensure that error is properly decorated and internal state is updated before throwing
   * @internal
   */
  private decorateCommandError(
    connection: Connection,
    cmd: Document,
    options: CommandOptions | GetMoreOptions | undefined,
    error: unknown
  ): Error {
    if (typeof error !== 'object' || error == null || !('name' in error)) {
      throw new MongoRuntimeError('An unexpected error type: ' + typeof error);
    }

    if (error.name === 'AbortError' && 'cause' in error && error.cause instanceof MongoError) {
      error = error.cause;
    }

    if (!(error instanceof MongoError)) {
      // Node.js or some other error we have not special handling for
      return error as Error;
    }

    if (connectionIsStale(this.pool, connection)) {
      return error;
    }

    const session = options?.session;
    if (error instanceof MongoNetworkError) {
      if (session && !session.hasEnded && session.serverSession) {

View on GitHub (pinned to dce7939f86)