class RubyLLM::Fallback

A Fallback is a fallback model target configured with Chat#with_fallbacks. When the active model fails with a matching error, the chat retries the request with each fallback in order. Instances are yielded to Chat#before_fallback and Chat#after_fallback callbacks, enriched with the details of that attempt.

chat = RubyLLM.chat(model: "gpt-4.1")
              .with_fallbacks("gpt-4.1-mini", "claude-haiku-4-5")

chat.before_fallback do |fallback|
  puts "Falling back from #{fallback.from.id} to #{fallback.to.id}"
end

chat.after_fallback do |fallback|
  puts "Fallback #{fallback.succeeded? ? 'succeeded' : 'failed'}"
end

Constants

DEFAULT_ERRORS: The error classes that trigger a fallback when Chat#with_fallbacks is called without on:.

Attributes

attempt [R]

The fallback attempt number, starting at 1.

chat [R]

The Chat performing the fallback attempt.

error [R]

The error that triggered the fallback.

fallback_error [R]

The error raised by the fallback attempt itself, or nil if it succeeded.

from [R]

The Model the chat is falling back from.

id [R]

The model id of the fallback target.

model [R]

The Model object the fallback was configured with, or nil when it was configured with a model id.

provider [R]

The provider of the fallback target as a Symbol, or nil.

response [R]

The response Message from a successful fallback attempt, or nil.

to [R]

The Model the chat is falling back to.

Public Instance Methods

chunks_yielded? ()

Source

# File lib/ruby_llm/fallback.rb, line 111
def chunks_yielded?
  @chunks_yielded
end

Returns whether the failed model already yielded stream chunks before the fallback.

failed? ()

Source

# File lib/ruby_llm/fallback.rb, line 117
def failed?
  !fallback_error.nil?
end

Returns true if the fallback attempt raised an error, false otherwise.

streaming? ()

Source

# File lib/ruby_llm/fallback.rb, line 105
def streaming?
  streaming
end

Returns whether the fallback happened during a streaming request.

succeeded? ()

Source

# File lib/ruby_llm/fallback.rb, line 123
def succeeded?
  !response.nil? && !failed?
end

Returns true if the fallback attempt produced a response without error, false otherwise.