Exception: Mongo::Error::OperationFailure

Inherits:
Mongo::Error
  • Object
show all
Extended by:
Forwardable
Includes:
SdamErrorDetection
Defined in:
lib/mongo/error/operation_failure.rb

Overview

Raised when an operation fails for some reason.

Since:

  • 2.0.0

Constant Summary collapse

WRITE_RETRY_ERRORS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Error codes and code names that should result in a failing write being retried.

Since:

  • 2.6.0

[
  {: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 => 'NotMasterNoSlaveOk', :code => 13435},
  {:code_name => 'NotMasterOrSecondary', :code => 13436},
].freeze
WRITE_RETRY_MESSAGES =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

These are magic error messages that could indicate a master change.

Since:

  • 2.4.2

[
  'not master',
  'node is recovering',
].freeze
RETRY_MESSAGES =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

These are magic error messages that could indicate a cluster reconfiguration behind a mongos.

Since:

  • 2.1.1

WRITE_RETRY_MESSAGES + [
  'transport error',
  'socket exception',
  "can't connect",
  'connect failed',
  'error querying',
  'could not get last error',
  'connection attempt failed',
  'interrupted at shutdown',
  'unknown replica set',
  'dbclient error communicating with server'
].freeze
CHANGE_STREAM_RESUME_ERRORS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

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

Since:

  • 2.0.0

[
  {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: 'NotMasterNoSlaveOk', 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 =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Change stream can be resumed when these error messages are encountered.

Since:

  • 2.6.0

WRITE_RETRY_MESSAGES

Constants included from SdamErrorDetection

SdamErrorDetection::NODE_RECOVERING_CODES, SdamErrorDetection::NODE_SHUTTING_DOWN_CODES, SdamErrorDetection::NOT_MASTER_CODES

Constants inherited from Mongo::Error

BAD_VALUE, CODE, CURSOR_NOT_FOUND, ERR, ERRMSG, ERROR, TRANSIENT_TRANSACTION_ERROR_LABEL, UNKNOWN_ERROR, UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL, WRITE_CONCERN_ERROR, WRITE_CONCERN_ERRORS, WRITE_ERRORS

Instance Attribute Summary collapse

Attributes included from Notable

#generation

Instance Method Summary collapse

Methods included from SdamErrorDetection

#node_recovering?, #node_shutting_down?, #not_master?

Methods inherited from Mongo::Error

#add_label, #label?, #labels, #write_concern_error_label?, #write_concern_error_labels

Methods included from Notable

#add_note, #notes, #to_s

Constructor Details

#initialize(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) —

    Error code.

  • :code_name (String) —

    Error code name.

  • :write_concern_error_document (Hash) —

    The server-supplied write concern error document, if any.

  • :write_concern_error_code (Integer) —

    Error code for write concern error, if any.

  • :write_concern_error_code_name (String) —

    Error code name for write concern error, if any.

  • :write_concern_error_labels (Array<String>) —

    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.5.0, options added in 2.6.0



245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/mongo/error/operation_failure.rb', line 245

def initialize(message = nil, result = nil, options = {})
  super(message)
  @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]
end

Instance Attribute Details

#code ⇒ Integer (readonly)

Returns The error code parsed from the document.

Returns:

  • (Integer) —

    The error code parsed from the document.

Since:

  • 2.6.0



85
86
87
 
# File 'lib/mongo/error/operation_failure.rb', line 85

def code
  @code
end

#code_name ⇒ String (readonly)

Returns The error code name parsed from the document.

Returns:

  • (String) —

    The error code name parsed from the document.

Since:

  • 2.6.0



90
91
92
 
# File 'lib/mongo/error/operation_failure.rb', line 90

def code_name
  @code_name
end

#write_concern_error_code ⇒ Integer | nil (readonly)

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

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



210
211
212
 
# File 'lib/mongo/error/operation_failure.rb', line 210

def write_concern_error_code
  @write_concern_error_code
end

#write_concern_error_code_name ⇒ String | nil (readonly)

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

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



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

def write_concern_error_code_name
  @write_concern_error_code_name
end

#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



204
205
206
 
# File 'lib/mongo/error/operation_failure.rb', line 204

def write_concern_error_document
  @write_concern_error_document
end

Instance Method Details

#change_stream_resumable? ⇒ true, false

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



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/mongo/error/operation_failure.rb', line 167

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

#connection_description ⇒ Server::Description

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Returns:

  • (Server::Description) —

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



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

def_delegator :@result, :connection_description

#max_time_ms_expired? ⇒ true | false

Whether the error is MaxTimeMSExpired.

Returns:

  • (true | false) —

    Whether the error is MaxTimeMSExpired.

Since:

  • 2.10.0



272
273
274
 
# File 'lib/mongo/error/operation_failure.rb', line 272

def max_time_ms_expired?
  code == 50 # MaxTimeMSExpired
end

#retryable? ⇒ true, false

Deprecated.

Whether the error is a retryable error according to the legacy read retry logic.

Returns:

  • (true, false)

Since:

  • 2.1.1



99
100
101
 
# File 'lib/mongo/error/operation_failure.rb', line 99

def retryable?
  write_retryable? || RETRY_MESSAGES.any?{ |m| message.include?(m) }
end

#unsupported_retryable_write? ⇒ true | false

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



283
284
285
286
 
# File 'lib/mongo/error/operation_failure.rb', line 283

def unsupported_retryable_write?
  # code 20 is IllegalOperation
  code == 20 && message.start_with?("Transaction numbers")
end

#write_concern_error? ⇒ true | false

Returns 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.

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



196
197
198
 
# File 'lib/mongo/error/operation_failure.rb', line 196

def write_concern_error?
  !!@write_concern_error_document
end

#write_retryable? ⇒ true, false

Whether the error is a retryable error according to the modern retryable reads and retryable writes specifications.

This method is also used by the legacy retryable write logic to determine whether an error is a retryable one.

Returns:

  • (true, false)

Since:

  • 2.4.2



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

def write_retryable?
  WRITE_RETRY_MESSAGES.any? { |m| message.include?(m) } ||
  write_retryable_code?
end

#wtimeout? ⇒ true | false

Whether the error is a write concern timeout.

Returns:

  • (true | false) —

    Whether the error is a write concern timeout.

Since:

  • 2.7.1



263
264
265
 
# File 'lib/mongo/error/operation_failure.rb', line 263

def wtimeout?
  @wtimeout
end