Custom-exceptions

Learn about custom-exceptions in Ruby programming.

Home → Ruby → Custom-exceptions

Ruby Custom Exceptions Mastery

Learn how to design meaningful, domain-specific exceptions that improve error handling, simplify debugging, and make your Ruby applications more expressive and maintainable.

Why Create Custom Exceptions?

Custom Exceptions: Domain-specific error classes that provide meaningful context about what went wrong in your application. They enable precise handling, better debugging, and self-documenting code.

Benefits

Semantic meaning – clear indication of what failed
Selective handling – rescue specific error types
Rich context – include attributes and helpers
Better debugging – informative messages and data

Problems They Solve

Generic errors lack context
Broad rescue hides root causes
Inflexible handling for different failure modes

Basic Custom Exception Classes

# Custom exceptions typically inherit from StandardError

      class PaymentError < StandardError; end
      
      class UserNotFoundError < StandardError; end
      
      class ValidationError < StandardError; end
      
      def find_user(id)
        raise UserNotFoundError, "User with ID #{id} not found" unless user_exists?(id)
      end

Rich Exceptions with Data & Helpers

      class ValidationError < StandardError
        attr_reader :field, :value, :errors

        def initialize(message, field: nil, value: nil)
          super(message)
          @field  = field
          @value  = value
          @errors = {}
        end

        def add_error(field, message)
          @errors[field] ||= []
          @errors[field] << message
        end

        def full_messages
          msgs = [message]
          @errors.each { |k, arr| arr.each { |m| msgs << "#{k}: #{m}" } }
          msgs
        end
      end
    

Try It Yourself - Interactive Practice

Edit and run this code to experiment with custom exceptions.

Interactive Code Runner

Ruby Code Editor

# Custom Exceptions – Interactive Examples

class GameError < StandardError; end

class InvalidMoveError < GameError
  attr_reader :move, :valid_moves
  def initialize(move, valid_moves)
    super("Invalid move: #{move}. Valid moves: #{valid_moves.join(', ')}")
    @move = move
    @valid_moves = valid_moves
  end
end

class PlayerValidationError < GameError
  attr_reader :errors
  def initialize(message, errors: {})
    super(message)
    @errors = errors
  end
  def add_error(field, message)
    (@errors[field] ||= []) << message
  end
  def full_messages
    [message] + @errors.flat_map { |k, arr| arr.map { |m| "#{k}: #{m}" } }
  end
end

class TicTacToe
  def initialize
    @board = Array.new(9, nil)
    @current_player = "X"
  end

def make_move(position, player = nil)
    player ||= @current_player
    validate_player(player)
    valid_positions = (0..8).select { |i| @board[i].nil? }
    raise InvalidMoveError.new(position, valid_positions) unless valid_positions.include?(position)
    @board[position] = player
    switch_player
    "Player #{player} moves to position #{position}"
  end

private
  def validate_player(player)
    err = PlayerValidationError.new("Invalid player")
    err.add_error(:player, "cannot be empty") if player.nil? || player.empty?
    err.add_error(:player, "must be X or O") unless ["X", "O"].include?(player)
    raise err if err.errors.any?
  end
  def switch_player
    @current_player = @current_player == "X" ? "O" : "X"
  end
end

game = TicTacToe.new
begin
  puts game.make_move(0)      # X -> 0
  puts game.make_move(0)      # invalid, already taken
rescue InvalidMoveError => e
  puts "Invalid move: #{e.move}"
  puts "Valid: #{e.valid_moves.inspect}"
end

Output will appear here when you run the code...

Best Practices & Common Pitfalls

✅ Best Practices

Inherit from StandardError (not Exception)
Prefer descriptive names and helpful messages
Attach context data via attributes and helpers
Design small, logical hierarchies for flexible rescue

❌ Common Pitfalls

Using generic errors everywhere
Overly deep or broad exception hierarchies
Swallowing exceptions without logging/handling

Custom Exceptions Checklist

Design

Pick clear names and messages
Attach relevant context

Handling

Rescue narrowly when possible
Log and surface helpful details

Ruby Custom Exceptions Mastery

Master the art of creating custom exception classes in Ruby. Learn how to design meaningful error types that make your applications more maintainable, debuggable, and expressive.

Why Create Custom Exceptions?

Custom Exceptions: Domain-specific error classes that provide meaningful context about what went wrong in your application. They make error handling more precise, debugging easier, and code more self-documenting.

Benefits Why Use Custom Exceptions?

Semantic meaning: Clear indication of what failed
Selective handling: Rescue specific error types
Rich context: Include relevant data with errors
Better debugging: More informative error messages
API design: Clear error contracts for users
Maintainability: Easier to modify error handling

Problems Problems Custom Exceptions Solve

Generic errors: "Something went wrong" tells us nothing
Lost context: Important error details are missing
Broad rescue: Catching too many unrelated errors
Poor UX: Users see cryptic technical messages
Hard debugging: Difficult to trace error sources
Inflexible handling: Same response to different errors

Real-World Analogy

Think of custom exceptions like different types of alarms: A fire alarm sounds different from a security alarm or a medical emergency alert. Each has a specific sound and response protocol. Similarly, custom exceptions help your code "sound different alarms" for different types of problems, allowing appropriate responses to each situation.

Basic Custom Exception Classes

Basic Pattern: Custom exceptions inherit from StandardError (or its subclasses) and can include additional data and methods to provide context about what went wrong.

Simple Custom Exceptions

# Simplest custom exception - just inherits from StandardError
class
CustomError
 < StandardError
end

# Domain-specific exceptions
class
PaymentError
 < StandardError
end

class
UserNotFoundError
 < StandardError
end

class
ValidationError
 < StandardError
end

# Usage
def
process_payment
(amount)
          raise
PaymentError
, "Insufficient funds"
if
 amount > balance
          raise
PaymentError
, "Invalid amount"
if
 amount <= 0
  # Process payment...
end

def
find_user
(id)
          raise
UserNotFoundError
, "User with ID #{id} not found"
unless
 user_exists?(id)
          # Return user...
end

Exceptions with Custom Messages

# Exception with default message
class
DatabaseConnectionError
 < StandardError
  def
initialize
(message = "Unable to connect to database"
)
            super
(message)
          end
end

# Exception with formatted message
class
FileNotFoundError
 < StandardError
  def
initialize
(filename)
            super
("File not found: #{filename}"
)
            @filename = filename
  end

  attr_reader :filename
end

# Usage examples
begin
  raise
DatabaseConnectionError
# Uses default message
rescue
DatabaseConnectionError
 => e
          puts e.message  # "Unable to connect to database"
end

begin
  raise
FileNotFoundError
.new("config.yml"
)
        rescue
FileNotFoundError
 => e
          puts e.message    # "File not found: config.yml"
  puts e.filename   # "config.yml"
end

Rich Exception Classes with Data

Rich Exceptions: Include additional data, status codes, and methods to provide comprehensive context about errors. These make debugging and error handling much more powerful.

Validation Errors with Field Details

# Comprehensive validation error class
class
ValidationError
 < StandardError
  attr_reader :field, :value, :rule, :errors

  def
initialize
(message, field: nil
, value: nil
, rule: nil
, errors: {})
            super
(message)
            @field = field
    @value = value
    @rule = rule
    @errors = errors
  end

  def
add_error
(field, message)
            @errors[field] ||= []
    @errors[field] << message
  end

  def
has_errors?
    !@errors.empty?
  end

  def
full_messages
    messages = [message]
    @errors.each do |field, field_errors|
      field_errors.each { |error| messages << "#{field}: #{error}"
 }
    end
    messages
  end

  def
to_hash
    {
      message: message,
      field: @field,
      value: @value,
      rule: @rule,
      errors: @errors
    }
  end
end

# Usage example
def
validate_user
(user_data)
          error = ValidationError
.new("User validation failed"
)

  error.add_error(:email, "is required"
) if
 user_data[:email].nil?
  error.add_error(:email, "must be valid"
) unless
 valid_email?(user_data[:email])
  error.add_error(:age, "must be 18 or older"
) if
 user_data[:age] < 18

  raise
 error if
 error.has_errors?

end

HTTP-Style Errors with Status Codes

# HTTP-style error with status codes
class
APIError
 < StandardError
  attr_reader :status_code, :error_code, :details, :timestamp

  def
initialize
(message, status_code: 500
, error_code: nil
, details: {})
            super
(message)
            @status_code = status_code
    @error_code = error_code
    @details = details
    @timestamp = Time
.now
  end

  def
client_error?
    @status_code >= 400
 && @status_code < 500
  end

  def
server_error?
    @status_code >= 500
  end

  def
to_json
    {
      error: {
        message: message,
        status_code: @status_code,
        error_code: @error_code,
        details: @details,
        timestamp: @timestamp.iso8601
      }
    }.to_json
  end
end

# Specific API error types
class
NotFoundError
 < APIError
  def
initialize
(resource, id = nil
)
            message = id ? "#{resource} with ID #{id} not found"
 : "#{resource} not found"
    super
(message, status_code: 404
, error_code: "NOT_FOUND"
, details: { resource: resource, id: id })

end

class

UnauthorizedError

APIError

def

initialize

(action =

nil

)

message = action ?

"Unauthorized to #{action}"

"Unauthorized access"

super

(message, status_code:

401

, error_code:

"UNAUTHORIZED"

, details: { action: action })

# Business rule violation with rich context

class

BusinessRuleError

StandardError

attr_reader :rule_name, :entity, :context, :suggestions

def

initialize

(message, rule_name:, entity:

nil

, context: {}, suggestions: [])

super

(message)

@rule_name = rule_name

@entity = entity

@context = context

@suggestions = suggestions

end

def

detailed_message

msg = [

"Business Rule Violation: #{@rule_name}"

]

msg <<

"Error: #{message}"

msg <<

"Entity: #{@entity.class.name} (ID: #{@entity.id})"

@entity&.respond_to?(:id)

unless

@context.empty?

@context.each { |key, value| msg <<

" #{key}: #{value}"

}

msg <<

"Suggestions:"

@suggestions.each { |suggestion| msg <<

" - #{suggestion}"

}

# Usage in business logic

"Insufficient funds for transfer"

rule_name:

"sufficient_balance"

entity: from_account,

requested_amount: amount,

available_balance: from_account.balance,

shortfall: amount - from_account.balance

"Reduce transfer amount to $#{from_account.balance}"

"Add funds to account first"

"Contact customer service for overdraft options"

# Proceed with transfer...

Exception Hierarchies: Organize related exceptions in inheritance trees. This allows you to catch broad categories of errors or specific types, making your error handling both flexible and precise.

Application-Level Exception Hierarchy

# Base application error
module
MyApp
  class
Error
 < StandardError
    attr_reader :context, :severity

    def
initialize
(message, context: {}, severity: :error
)
              super
(message)
              @context = context
      @severity = severity
    end

    def
critical?
      @severity == :critical
    end
  end

  # Authentication & Authorization errors
  class
SecurityError
 < Error
; end

  class
AuthenticationError
 < SecurityError
    def
initialize
(message = "Authentication failed"
, **options)
              super
(message, **options)
            end
  end

  class
AuthorizationError
 < SecurityError
    def
initialize
(action, **options)
              super
("Not authorized to #{action}"
, **options)
              @action = action
    end

    attr_reader :action
  end

  # Data-related errors
  class
DataError
 < Error
; end

  class
ValidationError
 < DataError
; end
  class
NotFoundError
 < DataError
; end
  class
DuplicateError
 < DataError
; end

  # External service errors
  class
ExternalServiceError
 < Error
    def
initialize
(service_name, **options)
              super
("External service error: #{service_name}"
, **options)
              @service_name = service_name
    end

    attr_reader :service_name
  end

  class
APIError
 < ExternalServiceError
; end
  class
DatabaseError
 < ExternalServiceError
; end
  class
NetworkError
 < ExternalServiceError
; end
end

Using the Exception Hierarchy

# Using the hierarchy for flexible error handling
def
process_user_request
(user, action, data)
          begin
    authenticate_user(user)
    authorize_action(user, action)
    validate_data(data)
    save_to_database(data)
    send_notification(user)

  # Catch specific errors for tailored handling
  rescue
MyApp::AuthenticationError
 => e
            log_security_event(e)
    { error: "Please log in"
, status: 401
 }

  rescue
MyApp::AuthorizationError
 => e
            log_security_event(e)
    { error: "Access denied"
, status: 403
 }

  rescue
MyApp::ValidationError
 => e
            { error: "Invalid data"
, details: e.context, status: 400
 }

  # Catch broad categories
  rescue
MyApp::SecurityError
 => e
            log_security_event(e)
    { error: "Security error"
, status: 403
 }

  rescue
MyApp::DataError
 => e
            { error: "Data error"
, message: e.message, status: 400
 }

  rescue
MyApp::ExternalServiceError
 => e
            log_service_error(e)
    notify_ops_team(e) if
 e.critical?
    { error: "Service temporarily unavailable"
, status: 503
 }

  # Catch all application errors
  rescue
MyApp::Error
 => e
            log_application_error(e)
    { error: "Application error"
, status: 500
 }

  # Unexpected errors
  rescue
 => e
            log_unexpected_error(e)
    notify_developers(e)
    { error: "Internal server error"
, status: 500
 }
  end
end

Practice Time: Experiment with creating and using custom exceptions. Try building your own exception hierarchy and see how it makes error handling more expressive and maintainable.

Interactive Code Runner

Ruby Code Editor

# Let's create and use comprehensive custom exceptions!

puts "=== Custom Exception Examples ==="

# 1. Basic custom exception
class GameError < StandardError
end

class InvalidMoveError < GameError
  def initialize(move, valid_moves)
    super("Invalid move: #{move}. Valid moves: #{valid_moves.join(', ')}")
    @move = move
    @valid_moves = valid_moves
  end

attr_reader :move, :valid_moves
end

# 2. Rich validation error
class PlayerValidationError < GameError
  def initialize(message, errors: {})
    super(message)
    @errors = errors
  end

attr_reader :errors

def add_error(field, message)
    @errors[field] ||= []
    @errors[field] << message
  end

def has_errors?
    !@errors.empty?
  end

def full_messages
    messages = [message]
    @errors.each do |field, field_errors|
      field_errors.each { |error| messages << "#{field}: #{error}" }
    end
    messages
  end
end

# 3. Game state error with context
class GameStateError < GameError
  def initialize(message, current_state:, expected_state:, player: nil)
    super(message)
    @current_state = current_state
    @expected_state = expected_state
    @player = player
  end

attr_reader :current_state, :expected_state, :player

def detailed_message
    msg = [message]
    msg << "Current state: #{@current_state}"
    msg << "Expected state: #{@expected_state}"
    msg << "Player: #{@player}" if @player
    msg.join("\n")
  end
end

# 4. Using custom exceptions in a simple game
class TicTacToe
  def initialize
    @board = Array.new(9, nil)
    @current_player = "X"
    @game_state = :playing
  end

def make_move(position, player = nil)
    # Validate player
    player ||= @current_player
    validate_player(player)

# Validate game state
    if @game_state != :playing
      raise GameStateError.new(
        "Cannot make move when game is #{@game_state}",
        current_state: @game_state,
        expected_state: :playing,
        player: player
      )
    end

# Validate move
    valid_positions = (0..8).select { |i| @board[i].nil? }
    unless valid_positions.include?(position)
      raise InvalidMoveError.new(position, valid_positions)
    end

# Make the move
    @board[position] = player
    switch_player
    check_game_end

"Player #{player} moves to position #{position}"
  end

private

def validate_player(player)
    error = PlayerValidationError.new("Invalid player")

if player.nil? || player.empty?
      error.add_error(:player, "cannot be empty")
    end

unless ["X", "O"].include?(player)
      error.add_error(:player, "must be X or O")
    end

if player != @current_player
      error.add_error(:turn, "not your turn (current: #{@current_player})")
    end

raise error if error.has_errors?
  end

def switch_player
    @current_player = @current_player == "X" ? "O" : "X"
  end

def check_game_end
    # Simplified win detection
    lines = [
      [0, 1, 2], [3, 4, 5], [6, 7, 8],  # rows
      [0, 3, 6], [1, 4, 7], [2, 5, 8],  # columns
      [0, 4, 8], [2, 4, 6]              # diagonals
    ]

lines.each do |line|
      values = line.map { |i| @board[i] }
      if values.uniq.size == 1 && !values[0].nil?
        @game_state = :won
        return
      end
    end

if @board.none?(&:nil?)
      @game_state = :draw
    end
  end

def display_board
    (0..2).map do |row|
      (0..2).map { |col| @board[row * 3 + col] || (row * 3 + col) }.join(" | ")
    end.join("\n---------\n")
  end
end

# 5. Demonstrate comprehensive error handling
puts "\n=== Testing Custom Exceptions ==="

game = TicTacToe.new
puts "Starting new game:"
puts game.display_board

# Test valid moves
begin
  puts "\n" + game.make_move(0)  # X moves to 0
  puts game.make_move(1)         # O moves to 1
  puts game.make_move(4)         # X moves to 4
rescue GameError => e
  puts "Game error: #{e.message}"
end

# Test invalid move
begin
  puts "\nTrying invalid move..."
  game.make_move(0)  # Position already taken
rescue InvalidMoveError => e
  puts "Invalid move error:"
  puts "  Move: #{e.move}"
  puts "  Valid moves: #{e.valid_moves}"
  puts "  Message: #{e.message}"
end

# Test player validation
begin
  puts "\nTrying invalid player..."
  game.make_move(2, "Z")  # Invalid player
rescue PlayerValidationError => e
  puts "Player validation error:"
  puts "  Message: #{e.message}"
  e.full_messages.each { |msg| puts "  - #{msg}" }
end

# Test wrong turn
begin
  puts "\nTrying wrong turn..."
  game.make_move(2, "X")  # Wrong turn (should be O)
rescue PlayerValidationError => e
  puts "Turn error: #{e.message}"
  e.errors.each { |field, messages| puts "  #{field}: #{messages.join(', ')}" }
end

# 6. Exception hierarchy demonstration
puts "\n=== Exception Hierarchy Demo ==="

def demonstrate_catch_hierarchy
  begin
    # This could raise any type of GameError
    case rand(3)
    when 0
      raise InvalidMoveError.new(5, [2, 3, 6])
    when 1
      error = PlayerValidationError.new("Bad player")
      error.add_error(:name, "too short")
      raise error
    when 2
      raise GameStateError.new("Game over", current_state: :won, expected_state: :playing)
    end

rescue InvalidMoveError => e
    puts "Caught InvalidMoveError: #{e.move}"
  rescue PlayerValidationError => e
    puts "Caught PlayerValidationError: #{e.errors.keys.join(', ')}"
  rescue GameStateError => e
    puts "Caught GameStateError: #{e.current_state} -> #{e.expected_state}"
  rescue GameError => e
    puts "Caught general GameError: #{e.message}"
  end
end

3.times { demonstrate_catch_hierarchy }

puts "\n=== Custom Exception Benefits ==="
puts "✓ Specific error types for precise handling"
puts "✓ Rich context data for debugging"
puts "✓ Hierarchical organization for flexible catching"
puts "✓ Self-documenting error conditions"
puts "✓ Better user experience with meaningful messages"

# Try creating your own custom exceptions below!

Output will appear here when you run the code...

✅ Best Practices

Inherit from StandardError: Never inherit from Exception directly
Use meaningful names: Exception names should clearly indicate what failed
Include context data: Store relevant information as attributes
Provide good messages: Make error messages helpful for users and developers
Build hierarchies: Group related exceptions for flexible catching
Document exceptions: Specify what exceptions methods can raise
Use modules for namespacing: Avoid global exception name conflicts

❌ Common Pitfalls

Too many exceptions: Don't create exceptions for every possible error
Generic names: Avoid names like Error, Failure, or Problem
No context: Don't just inherit without adding value
Deep hierarchies: Keep inheritance trees shallow and logical
Exposing internals: Don't leak implementation details in error messages
Poor inheritance: Don't inherit from built-in exceptions inappropriately
Missing documentation: Always document custom exceptions

Design Guidelines

Naming Conventions:

End with "Error" for clarity
Use domain-specific prefixes
Be descriptive but concise
Reflect the nature of the problem

Content Guidelines:

Include relevant data as attributes
Provide helpful error messages
Add methods for common queries
Consider serialization needs

You've Mastered Ruby Custom Exceptions!

Domain-Specific Errors

Meaningful exceptions that reflect your business logic

Rich Context

Exceptions with data, methods, and debugging information

Organized Hierarchies

Logical inheritance trees for flexible error handling

Custom exceptions are a powerful tool for creating maintainable, debuggable applications. They provide semantic meaning to errors, enable precise error handling, and make your code self-documenting. Use them to create clear contracts between different parts of your application and to provide excellent user experiences.

Video Tutorial

Watch and learn custom-exceptions

Pro Tip: After reading through the content above, watch this video to reinforce your understanding and see the concepts in action!

Ruby Language

Rails Framework

Production Ready

Custom-exceptions

Ruby Custom Exceptions Mastery

Why Create Custom Exceptions?

Benefits

Problems They Solve

Basic Custom Exception Classes

Rich Exceptions with Data & Helpers

Try It Yourself - Interactive Practice

Interactive Code Runner

Ruby Code Editor

Best Practices & Common Pitfalls

✅ Best Practices

❌ Common Pitfalls

Custom Exceptions Checklist

Design

Handling

Ruby Custom Exceptions Mastery

Why Create Custom Exceptions?

Benefits Why Use Custom Exceptions?

Problems Problems Custom Exceptions Solve

Real-World Analogy

Basic Custom Exception Classes

Simple Custom Exceptions

Exceptions with Custom Messages

Rich Exception Classes with Data

Validation Errors with Field Details

HTTP-Style Errors with Status Codes

Business Logic Errors with Context

Building Exception Hierarchies

Application-Level Exception Hierarchy

Using the Exception Hierarchy

Interactive Practice: Custom Exceptions

Interactive Code Runner

Ruby Code Editor

Best Practices & Guidelines

✅ Best Practices

❌ Common Pitfalls

Design Guidelines

Naming Conventions:

Content Guidelines:

Custom Exceptions Mastery Summary

You've Mastered Ruby Custom Exceptions!

Domain-Specific Errors

Rich Context

Organized Hierarchies

Quick Navigation

Related Topics

Video Tutorial