Exception: Mongo::Error::OperationFailure

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, Forwardable, `::Mongo::Error`, StandardError
Instance Chain: self, `ReadWriteRetryable`, `SdamErrorDetection`, `::Mongo::Error`, `ChangeStreamResumable`, `WriteRetryable`, `Labelable`, `Notable`, StandardError
Inherits:	Mongo::Error Object StandardError Mongo::Error Mongo::Error::OperationFailure
Defined in:	lib/mongo/error/operation_failure.rb

Overview

Raised when an operation fails for some reason.

Since:

2.0.0

Constant Summary

CHANGE_STREAM_RESUME_ERRORS = Internal use only

::Mongo::Error codes and code names that should result in a failing getMore command on a change stream NOT being resumed.

Since:

2.0.0

# File 'lib/mongo/error/operation_failure.rb', line 60

[
  {code_name: 'HostUnreachable', code: 6},
  {code_name: 'HostNotFound', code: 7},
  {code_name: 'NetworkTimeout', code: 89},
  {code_name: 'ShutdownInProgress', code: 91},
  {code_name: 'PrimarySteppedDown', code: 189},
  {code_name: 'ExceededTimeLimit', code: 262},
  {code_name: 'SocketException', code: 9001},
  {code_name: 'NotMaster', code: 10107},
  {code_name: 'InterruptedAtShutdown', code: 11600},
  {code_name: 'InterruptedDueToReplStateChange', code: 11602},
  {code_name: 'NotPrimaryNoSecondaryOk', code: 13435},
  {code_name: 'NotMasterOrSecondary', code: 13436},

  {code_name: 'StaleShardVersion', code: 63},
  {code_name: 'FailedToSatisfyReadPreference', code: 133},
  {code_name: 'StaleEpoch', code: 150},
  {code_name: 'RetryChangeStream', code: 234},
  {code_name: 'StaleConfig', code: 13388},
].freeze

CHANGE_STREAM_RESUME_MESSAGES = Internal use only

Change stream can be resumed when these error messages are encountered.
Since:
- 2.6.0
# File 'lib/mongo/error/operation_failure.rb', line 85
```
ReadWriteRetryable::WRITE_RETRY_MESSAGES
```

Class Method Summary

.new(message = nil, result = nil, options = {}) ⇒ OperationFailure constructor

Create the operation failure.

`::Mongo::Error` - Inherited

.new

Instance Attribute Summary

#change_stream_resumable? ⇒ true, false readonly

Can the change stream on which this error occurred be resumed, provided the operation that triggered this error was a getMore?
#code ⇒ Integer readonly
#code_name ⇒ String readonly
#details ⇒ String | nil readonly
#document ⇒ BSON::Document | nil readonly
#max_time_ms_expired? ⇒ true | false readonly

Whether the error is MaxTimeMSExpired.
#server_message ⇒ String readonly
#unsupported_retryable_write? ⇒ true | false readonly

Whether the error is caused by an attempted retryable write on a storage engine that does not support retryable writes.
#write_concern_error? ⇒ true | false readonly
#write_concern_error_code ⇒ Integer | nil readonly
#write_concern_error_code_name ⇒ String | nil readonly
#write_concern_error_document ⇒ Hash | nil readonly

Returns the write concern error document as it was reported by the server, if any.
#wtimeout? ⇒ true | false readonly

Whether the error is a write concern timeout.
#change_stream_resumable_code? ⇒ Boolean readonly private

`ReadWriteRetryable` - Included

#retryable?	Whether the error is a retryable error according to the legacy read retry logic.
#write_retryable?	Whether the error is a retryable error according to the modern retryable reads and retryable writes specifications.
#write_retryable_code?

`SdamErrorDetection` - Included

#node_recovering?	Whether the error is a “node is recovering” error, or one of its variants.
#node_shutting_down?	Whether the error is a “node is shutting down” type error.
#not_master?	Whether the error is a “not master” error, or one of its variants.

`::Mongo::Error` - Inherited

#change_stream_resumable?

Can the change stream on which this error occurred be resumed, provided the operation that triggered this error was a getMore?

`ChangeStreamResumable` - Included

#change_stream_resumable?

Can the change stream on which this error occurred be resumed, provided the operation that triggered this error was a getMore?

`WriteRetryable` - Included

#write_retryable?

`Notable` - Included

#connection_global_id	Returns global id of the connection on which the error occurred.
#generation	Returns connection pool generation for the connection on which the error occurred.
#service_id	Returns service id for the connection on which the error occurred.

Instance Method Summary

#connection_description ⇒ Server::Description Internal use only
#append_details(message, details) ⇒ String private

Append the details to the message.
#retrieve_details(document) ⇒ Hash | nil private

Retrieve the details from a document.

`::Mongo::Error` - Inherited

#write_concern_error_label?	Does the write concern error have the given label?
#write_concern_error_labels	The set of error labels associated with the write concern error.

`Labelable` - Included

#add_label	Adds the specified label to the error instance, if the label is not already in the set of labels.
#label?	Does the error have the given label?
#labels	Gets the set of labels associated with the error.

`Notable` - Included

#add_note,
#add_notes	Allows multiple notes to be added in a single call, for convenience.
#notes	Returns an array of strings with additional information about the exception.
#to_s, #notes_tail

Constructor Details

.new(message = nil, result = nil, options = {}) ⇒ `OperationFailure`

Create the operation failure.

Examples:

Create the error object

OperationFailure.new(message, result)

Create the error object with a code and a code name

OperationFailure.new(message, result, :code => code, :code_name => code_name)

Parameters:

message (String) (defaults to: nil) —

The error message.
result (Operation::Result) (defaults to: nil) —

The result object.
options (Hash) (defaults to: {}) —

Additional parameters.

Options Hash (options):

:code (Integer) —

::Mongo::Error code.
:code_name (String) —

::Mongo::Error code name.
:document (BSON::Document) —

The server-returned error document.
server_message (String) —

The server-returned error message parsed from the response.
:write_concern_error_document (Hash) —

The server-supplied write concern error document, if any.
:write_concern_error_code (Integer) —

::Mongo::Error code for write concern error, if any.
:write_concern_error_code_name (String) —

::Mongo::Error code name for write concern error, if any.
:write_concern_error_labels (Array<String>) —

::Mongo::Error labels for the write concern error, if any.
:labels (Array<String>) —

The set of labels associated with the error.
:wtimeout (true | false) —

Whether the error is a wtimeout.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 187


def initialize(message = nil, result = nil, options = {})
  @details = retrieve_details(options[:document])
  super(append_details(message, @details))

  @result = result
  @code = options[:code]
  @code_name = options[:code_name]
  @write_concern_error_document = options[:write_concern_error_document]
  @write_concern_error_code = options[:write_concern_error_code]
  @write_concern_error_code_name = options[:write_concern_error_code_name]
  @write_concern_error_labels = options[:write_concern_error_labels] || []
  @labels = options[:labels] || []
  @wtimeout = !!options[:wtimeout]
  @document = options[:document]
  @server_message = options[:server_message]
end

Instance Attribute Details

#change_stream_resumable? ⇒ `true`, `false` (readonly)

Can the change stream on which this error occurred be resumed, provided the operation that triggered this error was a getMore?

Examples:

Is the error resumable for the change stream?

error.change_stream_resumable?

Returns:

(true, false) —

Whether the error is resumable.

Since:

2.6.0

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 96


def change_stream_resumable?
  if @result && @result.is_a?(Mongo::Operation::GetMore::Result)
    # CursorNotFound exceptions are always resumable because the server
    # is not aware of the cursor id, and thus cannot determine if
    # the cursor is a change stream and cannot add the
    # ResumableChangeStreamError label.
    return true if code == 43

    # Connection description is not populated for unacknowledged writes.
    if connection_description.max_wire_version >= 9
      label?('ResumableChangeStreamError')
    else
      change_stream_resumable_code?
    end
  else
    false
  end
end

#change_stream_resumable_code? ⇒ `Boolean` (readonly, private)

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 115


def change_stream_resumable_code?
  CHANGE_STREAM_RESUME_ERRORS.any? { |e| e[:code] == code }
end

#code ⇒ `Integer` (readonly)

Returns:

(Integer) —

The error code parsed from the document.

Since:

2.6.0

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 43


attr_reader :code

#code_name ⇒ `String` (readonly)

Returns:

(String) —

The error code name parsed from the document.

Since:

2.6.0

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 48


attr_reader :code_name

#details ⇒ `String` | `nil` (readonly)

Returns:

(String | nil) —

The details of the error. For WriteConcernErrors this is ‘document[’errInfo’]‘. For WriteErrors this is `document[0]`. For all other errors this is nil.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 151


attr_reader :details

#document ⇒ `BSON::Document` | `nil` (readonly)

Returns:

(BSON::Document | nil) —

The server-returned error document.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 156


attr_reader :document

#max_time_ms_expired? ⇒ `true` | `false` (readonly)

Whether the error is MaxTimeMSExpired.

Returns:

(true | false) —

Whether the error is MaxTimeMSExpired.

Since:

2.10.0

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 218


def max_time_ms_expired?
  code == 50 # MaxTimeMSExpired
end

#server_message ⇒ `String` (readonly)

Returns:

(String) —

The server-returned error message parsed from the response.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 54


attr_reader :server_message

#unsupported_retryable_write? ⇒ `true` | `false` (readonly)

Whether the error is caused by an attempted retryable write on a storage engine that does not support retryable writes.

retryable write on a storage engine that does not support retryable writes.

Returns:

(true | false) —

Whether the error is caused by an attempted

Since:

2.10.0

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 229


def unsupported_retryable_write?
  # code 20 is IllegalOperation.
  # Note that the document is expected to be a BSON::Document, thus
  # either having string keys or providing indifferent access.
  code == 20 && server_message&.start_with?("Transaction numbers") || false
end

#write_concern_error? ⇒ `true` | `false` (readonly)

Returns:

(true | false) —

Whether the failure includes a write concern error. A failure may have a top level error and a write concern error or either one of the two.

Since:

2.10.0

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 125


def write_concern_error?
  !!@write_concern_error_document
end

#write_concern_error_code ⇒ `Integer` | `nil` (readonly)

Returns:

(Integer | nil) —

The error code for the write concern error, if a write concern error is present and has a code.

Since:

2.10.0

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 139


attr_reader :write_concern_error_code

#write_concern_error_code_name ⇒ `String` | `nil` (readonly)

Returns:

(String | nil) —

The code name for the write concern error, if a write concern error is present and has a code name.

Since:

2.10.0

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 145


attr_reader :write_concern_error_code_name

#write_concern_error_document ⇒ `Hash` | `nil` (readonly)

Returns the write concern error document as it was reported by the server, if any.

Returns:

(Hash | nil) —

Write concern error as reported to the server.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 133


attr_reader :write_concern_error_document

#wtimeout? ⇒ `true` | `false` (readonly)

Whether the error is a write concern timeout.

Returns:

(true | false) —

Whether the error is a write concern timeout.

Since:

2.7.1

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 209


def wtimeout?
  @wtimeout
end

Instance Method Details

#append_details(message, details) ⇒ `String` (private)

Append the details to the message

Returns:

(String) —

the message with the details appended to it

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 253


def append_details(message, details)
  return message unless details && message
  message + " -- #{details.to_json}"
end

#connection_description ⇒ Server::Description

Returns:

(Server::Description) —

::Mongo::Server description of the server that the operation that this exception refers to was performed on.

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 38


def_delegator :@result, :connection_description

#retrieve_details(document) ⇒ `Hash` | `nil` (private)

Retrieve the details from a document

Returns:

(Hash | nil) —

the details extracted from the document

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/error/operation_failure.rb', line 241


def retrieve_details(document)
  return nil unless document
  if wce = document['writeConcernError']
    return wce['errInfo']
  elsif we = document['writeErrors']&.first
    return we['errInfo']
  end
end

Exception: Mongo::Error::OperationFailure

Overview

Constant Summary

::Mongo::Error - Inherited

SdamErrorDetection - Included

ReadWriteRetryable - Included

Class Method Summary

::Mongo::Error - Inherited

Instance Attribute Summary

ReadWriteRetryable - Included

SdamErrorDetection - Included

::Mongo::Error - Inherited

ChangeStreamResumable - Included

WriteRetryable - Included

Notable - Included

Instance Method Summary

::Mongo::Error - Inherited

Labelable - Included

Notable - Included

Constructor Details

.new(message = nil, result = nil, options = {}) ⇒ OperationFailure

Instance Attribute Details

#change_stream_resumable? ⇒ true, false (readonly)

#change_stream_resumable_code? ⇒ Boolean (readonly, private)

#code ⇒ Integer (readonly)

#code_name ⇒ String (readonly)

#details ⇒ String | nil (readonly)

#document ⇒ BSON::Document | nil (readonly)

#max_time_ms_expired? ⇒ true | false (readonly)

#server_message ⇒ String (readonly)

#unsupported_retryable_write? ⇒ true | false (readonly)

#write_concern_error? ⇒ true | false (readonly)

#write_concern_error_code ⇒ Integer | nil (readonly)

#write_concern_error_code_name ⇒ String | nil (readonly)

#write_concern_error_document ⇒ Hash | nil (readonly)

#wtimeout? ⇒ true | false (readonly)

Instance Method Details

#append_details(message, details) ⇒ String (private)

#connection_description ⇒ Server::Description

#retrieve_details(document) ⇒ Hash | nil (private)

`::Mongo::Error` - Inherited

`SdamErrorDetection` - Included

`ReadWriteRetryable` - Included

`::Mongo::Error` - Inherited

`ReadWriteRetryable` - Included

`SdamErrorDetection` - Included

`::Mongo::Error` - Inherited

`ChangeStreamResumable` - Included

`WriteRetryable` - Included

`Notable` - Included

`::Mongo::Error` - Inherited

`Labelable` - Included

`Notable` - Included

.new(message = nil, result = nil, options = {}) ⇒ `OperationFailure`

#change_stream_resumable? ⇒ `true`, `false` (readonly)

#change_stream_resumable_code? ⇒ `Boolean` (readonly, private)

#code ⇒ `Integer` (readonly)

#code_name ⇒ `String` (readonly)

#details ⇒ `String` | `nil` (readonly)

#document ⇒ `BSON::Document` | `nil` (readonly)

#max_time_ms_expired? ⇒ `true` | `false` (readonly)

#server_message ⇒ `String` (readonly)

#unsupported_retryable_write? ⇒ `true` | `false` (readonly)

#write_concern_error? ⇒ `true` | `false` (readonly)

#write_concern_error_code ⇒ `Integer` | `nil` (readonly)

#write_concern_error_code_name ⇒ `String` | `nil` (readonly)

#write_concern_error_document ⇒ `Hash` | `nil` (readonly)

#wtimeout? ⇒ `true` | `false` (readonly)

#append_details(message, details) ⇒ `String` (private)

#retrieve_details(document) ⇒ `Hash` | `nil` (private)