mongodb/node-mongodb-native · error · MongoRuntimeError

Unreachable. If you are seeing this error, please file a…

Error message

Unreachable. If you are seeing this error, please file a ticket on the NODE driver project on Jira

What it means

Thrown in the CSOTTimeoutContext.connectionCheckoutTimeout getter in a branch the driver authors believe is unreachable: it fires only when _serverSelectionTimeout is neither an object (Timeout) nor null after the server selection timeout was already accessed. The message explicitly asks for a Jira ticket because it indicates an internal invariant violation.

Solutions

Upgrade to the latest driver patch release, as this indicates a bug that may already be fixed.
File a Jira ticket at https://jira.mongodb.org/projects/NODE with the full stack trace, driver version, and a reproduction.
As a temporary workaround, disable CSOT (remove timeoutMS from client/transaction options) to use legacy timeout mode.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await session.withTransaction(async (session) => {
    await collection.findOne({}, { session });
  }, { timeoutMS: 5000 });
} catch (e) {
  if (e instanceof MongoRuntimeError && /Unreachable/.test(e.message)) {
    // disable CSOT and retry, or report a bug
  } else throw e;
}

Prevention

Keep the driver on the latest patch release to pick up CSOT bug fixes.
If you see this, file a NODE Jira ticket with the stack trace and a minimal reproduction.
As a workaround, disable timeoutMS/CSOT on transactions to avoid the affected code path.

When it happens

Trigger: An internal driver race or logic error where the serverSelectionTimeout getter was not invoked or was cleared in an unexpected order before connectionCheckoutTimeout is read. This is not triggered by user configuration; it signals a driver bug under CSOT (Client-Side Operation Timeouts).

Common situations: Almost never seen. If encountered, it is typically during heavy concurrent use of CSOT-enabled transactions or when an operation is retried across a refreshed/cloned timeout context in an unexpected sequence.

Related errors

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

Appendix: source

Thrown at src/timeout.ts:272

        } else {
          this._serverSelectionTimeout = null;
        }
      }
    }

    return this._serverSelectionTimeout;
  }

  get connectionCheckoutTimeout(): Timeout | null {
    if (
      typeof this._connectionCheckoutTimeout !== 'object' ||
      this._connectionCheckoutTimeout?.cleared
    ) {
      if (typeof this._serverSelectionTimeout === 'object') {
        // null or Timeout
        this._connectionCheckoutTimeout = this._serverSelectionTimeout;
      } else {
        throw new MongoRuntimeError(
          'Unreachable. If you are seeing this error, please file a ticket on the NODE driver project on Jira'
        );
      }
    }
    return this._connectionCheckoutTimeout;
  }

  get timeoutForSocketWrite(): Timeout | null {
    const { remainingTimeMS } = this;
    if (!Number.isFinite(remainingTimeMS)) return null;
    if (remainingTimeMS > 0) return Timeout.expires(remainingTimeMS);
    return Timeout.reject(new MongoOperationTimeoutError('Timed out before socket write'));
  }

  get timeoutForSocketRead(): Timeout | null {
    const { remainingTimeMS } = this;
    if (!Number.isFinite(remainingTimeMS)) return null;
    if (remainingTimeMS > 0) return Timeout.expires(remainingTimeMS);

View on GitHub (pinned to dce7939f86)