account = Account.find(42)
account.plan = "growth"

account.changes_to_save
# => {
#   "plan" => ["starter", "growth"]
# }

The object has the right value. Dirty tracking has the right transition, but the save fails:

account.save
# => false

account.errors.full_messages
# => []

The row remains on the starter plan. The SQL log contains no UPDATE.

That missing UPDATE is useful evidence: save stopped before the adapter attempted the row write. It does not yet tell us what stopped it.

The cause lives in a concern included by Account:

module BillingMigrationGuard
  extend ActiveSupport::Concern

  included do
    before_update :prevent_plan_change_during_migration
  end

  private

  def prevent_plan_change_during_migration
    # An Account column maintained by the background billing migration.
    throw :abort if billing_migration_state == "running"
  end
end

The callback stopped the update after validation but before Active Record reached SQL. It added no error, so the caller received false without an explanation.

In a mature model, finding that callback may be harder than this example suggests. Start by inspecting the update chain:

Account._update_callbacks.map do |callback|
  [callback.kind, callback.filter]
end

The array may contain named methods, callback objects, and anonymous Proc instances installed by concerns, associations, or gems.

Callback inspection locates the guard. We still need to explain why save returned false, why errors stayed empty, and what else can commit after the update is refused.

save is assembled across Active Record

We already saw how an assignment becomes Active Record dirty-tracking state. Dirty tracking can describe the pending update:

account.plan_change_to_be_saved
# => ["starter", "growth"]

Persistence still has to accept and execute it.

Rails builds save by layering several modules around the same operation. ActiveRecord::Transactions supplies the outer wrapper:1

def save(**)
  with_transaction_returning_status { super }
end

ActiveRecord::Validations runs validation before delegating further:2

def save(**options)
  perform_validations(options) ? super : false
end

ActiveRecord::Callbacks wraps persistence in the save callbacks:3

def create_or_update(**)
  _run_save_callbacks { super }
end

Finally, ActiveRecord::Persistence#create_or_update selects _create_record or _update_record from new_record?.4 A new record takes the create callbacks and INSERT branch, with corresponding validation and callback cancellation points.

The method calls nest in this order because each module delegates inward with super. The transaction wrapper is entered before validation runs, so even a uniqueness validator’s SELECT runs inside the transaction that may later contain the INSERT or UPDATE. The SQL write appears near the inside of the operation, after validation and the relevant before callbacks have completed.

For an account update, the callback order around that write is:

1. before_save

2. before_update

3. timestamps handling and _update_record

4. after_update

5. after_save

Around callbacks wrap their corresponding save or update work.

Where save can stop

A validation failure and a callback abort both make non-bang save return false, but Rails reached different stages.

account.billing_email = nil

account.save
# => false

account.errors.full_messages
# => ["Billing email can't be blank"]

Validation populated errors and prevented the callback and persistence path from continuing. save! reports that failure with ActiveRecord::RecordInvalid.

The billing migration guard runs later. Validation passes, the update callbacks begin, and throw :abort halts the chain. save! reports with ActiveRecord::RecordNotSaved.

save returning false tells you that the lifecycle refused the write. It does not tell you which stage refused it.

The non-bang method is not an exception-free form of persistence. A raised callback exception, ActiveRecord::RecordNotUnique, ActiveRecord::StaleObjectError, a connection failure, or a readonly record still raises from save.

If callback inspection returns an anonymous block, ask Ruby where it was defined:

callback.filter.source_location if callback.filter.respond_to?(:source_location)

validate: false also has a narrower effect than its name can suggest:

account.save(validate: false)

It skips validation. The transaction wrapper, save callbacks, update callbacks, timestamps, and persistence still run. The billing migration guard can still abort this call.

That makes validate: false a poor substitute for a direct-write API. It bypasses one stage of save, not the model lifecycle.

One Rails boundary, explained each week

RailsRevelry follows ordinary Rails APIs into the framework source and back to the production behaviour they create.

If this helped you explain a save that returned false, subscribe free for next week’s article on what Active Record transactions actually protect.

Subscribe now

A callback can change the proposed write

Before callbacks can assign new values before Rails builds the statement:

before_update do 
  self.billing_email = billing_email.strip.downcase
end

Before save, changes_to_save may contain the address with its original whitespace. After this callback assigns the normalized address, dirty tracking and the eventual UPDATE contain the normalized value.

After a successful write, Rails clears the pending change and records the persisted transition in saved_changes. That history describes what reached the database, including changes made by before callbacks.

The billing migration guard has a larger effect: it vetoes the entire update.

Adding an error makes that veto visible:

def prevent_plan_change_during_migration
  return unless billing_migration_state == "running"

  errors.add(:plan, "cannot change during billing migration")
  throw :abort
end

It does not make the design explicit. A user-initiated plan change is a business operation with an expected refusal case. Hiding that decision in before_update means every caller has to discover the callback contract through false, errors, or source inspection.

An explicit upgrade operation can return a domain result before assigning the plan.

class UpgradeAccountPlan
  Result = Data.define(:status, :reason)

  def self.call(account, to:)
    if account.billing_migration_state == "running"
      return Result.new(
        status: :refused,
        reason: :billing_migration_running
      )
    end

    account.update!(plan: to)
    Result.new(status: :upgraded, reason: nil)
  end
end

Now the expected business refusal has a name:

result = UpgradeAccountPlan.call(account, to: "growth")

result.status
# => :refused

result.reason
# => :billing_migration_running

The callback can remain as protection against another persistence path bypassing the operation. But ordinary callers no longer have to infer a business decision from false and an empty errors collection.

The migration guard is an expected refusal; other persistence failures still raise from update!.

true does not require an UPDATE

An unchanged object can complete the save lifecycle:

account = Account.find(42)

account.has_changes_to_save?
# => false

account.save
# => true

The save lifecycle still completes, and its callbacks still run. An after_save callback therefore does not prove that the adapter executed a write. Code that publishes an event from after_save on the assumption that a row changed can publish work for a no-op save. If the event belongs to a plan change, guard it with saved_change_to_plan?; saved_changes? is broader and matches any persisted attribute change.

Moving external publication to after_commit protects it from a later transaction rollback. It solves a different problem and does not replace the attribute-change guard.

A failed save can leave the outer transaction running

The callback abort becomes more consequential inside a larger transaction. Consider a service that checks the result and returns it from the transaction block:

result = Account.transaction do
  AuditEvent.create!(
    account: account,
    event_type: "plan_upgrade_requested"
  )

  account.plan = "growth"
  saved = account.save
  Rails.logger.warn("Plan upgrade refused for Account #{account.id}") unless saved
  saved
end

result
# => false

The service reports failure, but the audit event commits. Returning false normally from an Account.transaction block does not ask Rails to roll that transaction back.

save always enters Active Record’s transaction wrapper.

• If no transaction is already open, the wrapper starts one for the save. When the save returns false, with_transaction_returning_status raises ActiveRecord::Rollback, and that transaction rolls back.

• If the caller already opened a transaction, as in the example above, save joins it. Rails does not create a savepoint for this ordinary nested transaction. The inner transaction call catches ActiveRecord::Rollback, returns control to the outer block, and the outer transaction continues.5

After the block:

account.reload.plan
# => "starter"

AuditEvent.exists?(
  account: account,
  event_type: "plan_upgrade_requested"
)
# => true

If the account update and audit event must succeed or fail together, the caller has to react to the failed save:

Account.transaction do
  AuditEvent.create!(
    account: account,
    event_type: "plan_upgrade_requested"
  )

  account.plan = "growth"
  account.save!
end

The callback abort now raises ActiveRecord::RecordNotSaved. Unless application code rescues it inside the transaction, the exception leaves the block, and Rails rolls back the outer transaction.

This is where the return value becomes part of the surrounding operation. false describes one refused save. It does not automatically refuse the transaction around it.

When save does not write:

1. Capture its return value or exception.

2. Inspect errors before rerunning validation.

3. Check the SQL log for an INSERT or UPDATE.

4. Inspect the save, create, or update callbacks.

5. Decide whether the surrounding transaction can continue.

First ask how far this save got. Then ask whether the larger transaction may still commit.

Rails sees two separate moments. Before the save, it needs to know what the next write would change. After the save, callbacks and application code may need to know what that write changed.

Confusing those questions can produce a bug even when the update itself succeeds.

A plan-change audit starts recording the wrong transition.

The account update succeeds, and the callback creates the audit row. Nothing raises, and the result looks close enough to correct:

class Account < ApplicationRecord
  before_update :record_plan_change

  private

  def record_plan_change
    AuditEvent.create!(
      account: self,
      from: plan_before_last_save,
      to: plan
    )
  end
end

The same Account instance has already been saved once, moving from trial to starter. Application code now changes that instance again, from starter to growth.

The audit should record:

start -> growth

Instead, it records:

trial -> growth

The callback asked Rails for a real value. It was the wrong value for that point in the record’s lifecycle.

plan_before_last_save returns the value before the most recent completed save. The before_update callback needs the change waiting to be written by the current save:

plan_change_to_be_saved
# => ["starter", "growth"]

Active Record exposes both answers because dirty tracking maintains two different comparisons. Before persistence, it compares the object’s database-driven value with its current in-memory value. After persistence, it preserves the transition made by the last save.

The similar method names are easier to reason about once the snapshots are explicit.

Assignment creates a pending change

Start with one loaded account:

account = Account.find(42)

account.plan
# => "starter"

A loaded Active Record object owns an in-memory snapshot. Reading account.plan reads the object’s attribute state. It does not query the row again.

Assignment changes that in-memory state:

account.plan = "growth"

account.plan
# => "growth"

No UPDATE has happened. Rails now has two relevant values for plan:

account.plan_in_database
# => "starter"

account.plan
# => "growth"

Despite its name, plan_in_database does not issue a fresh SELECT. It returns the database-derived value that this object uses as its baseline.

The pending-change APIs describe the difference:

account.will_save_change_to_plan?
# => true

account.plan_change_to_be_saved
# => ["starter", "growth"]

account.changes_to_save
# => {
#   "plan" => ["starter", "growth"]
# }

These methods inspect the proposed write, making them useful for validation and before callbacks. Assignment changed the Ruby object; dirty tracking describes what persistence would need to write to make the row match it.

Dirty tracking is not assignment history

Dirty tracking does not record every setter call.

account.plan
# => "starter"

account.plan = "growth"
account.plan = "starter"

account.will_save_change_to_plan?
# => false

account.plan_change_to_be_saved
# => nil

The setter ran twice, but the current value once again matches the database-derived baseline. There is no set attribute change for the next save.

Type casting is part of the same comparison. Suppose retry_limit is an integer column:

account.retry_limit
# => 5

account.retry_limit = "5"

account.retry_limit
# => 5

account.will_save_change_to_retry_limit?
# => false

The assigned input was a string. The value exposed by the model is the integer 5.

Active Record’s attribute types participate in dirty detection. The type-level changed? comparison receives the old and new values after type casting. For an ordinary value, the default question is equivalent to:

old_value != new_value

Both sides are 5, so Rails has no integer change to save.

This matters in request code because form parameters arrive as strings. A request that assigns "5" to an integer attribute already holding 5 has invoked a setter, but it has not proposed a different database value.

Dirty tracking is only meaningful when you name both sides of the comparison.

A save moves the comparison

Return to the pending plan change:

account.plan = "growth"

account.plan_change_to_be_saved
# => ["starter", "growth"]

Now save it:

account.save!

After the write, the pending-change APIs no longer describe that transition:

account.will_save_change_to_plan?
# => false

account.plan_change_to_be_saved
# => nil

account.plan_in_database
# => "growth"

The object’s current value and its database-derived baseline now agree.

Rails has not forgotten the transition. It moved it into the last-save comparison:

account.saved_change_to_plan?
# => true

account.saved_change_to_plan
# => ["starter", "growth"]

account.plan_before_last_save
# => "starter"

account.saved_changes
# => {
#   "plan" => ["starter", "growth"],
#   "updated_at" => [...]
# }

The lifecycle now looks like this:

Inside Rails, ActiveRecord::AttributeMethods::Dirty delegates the pending comparison to a mutation tracked called mutations_from_database. After Active Record creates or updates the row, changes_applied moves that tracker into mutations_before_last_save.

mutations_from_database
        |
        | changes_applied
        v
mutations_before_last_save

That handoff is why the public API has two families. The pending tracker answers what the next save would change. The saved tracker answers what the last save changed.

Callbacks ask different temporal questions

The original callback mixed those two families.

Before an update, inspect the change about to be written:

class Account < ApplicationRecord
  before_update :record_plan_change

  private

  def record_plan_change
    return unless will_save_change_to_plan?

    from, to = plan_change_to_be_saved

    AuditEvent.create!(
      account: self,
      from: from,
      to: to
    )
  end
end

After the update, a plan-history record needs the transition made by that save:

class Account < ApplicationRecord
  after_update :append_plan_history

  private

  def append_plan_history
    return unless saved_change_to_plan?

    from, to = saved_change_to_plan

    PlanHistory.create!(
      account: self,
      from: from,
      to: to
    )
  end
end

Rails introduced this split to make callback timing explicit: the will_save_* family describes the pending write, while the saved-change family describes the completed save.

Older code may express these checks through *_changed?, *_was?, or previous_changes. Do not translate those methods by name alone. First decide whether the callback needs the pending write (will_save_change_to_* and *_change_to_be_saved) or the completed save (saved_change_to_* and saved_changes).

saved_change_to_plan? says that the update completed within the model’s save lifecycle, not that an enclosing transaction committed. An after_update callback can run before the outer transaction commits or rolls back; work that depends on committed visibility belongs at the commit boundary.

Validations and before callbacks inspect pending changes. After callbacks inspect the changes made by the save that triggered them.

The baseline belongs to this object

plan_in_database sounds authoritative. Its authority is local to the model instance.

account = Account.find(42)
# account.plan => "starter"

# Another process updates account 42 to "enterprise".

account.plan_in_database
# => "starter"

That call does not ask PostgreSQL or MySQL what the row contains now. It asks the object’s mutation tracker for the database-driven value it has been comparing against.

The distinction from An Active Record Object Is a Snapshot, Not the Row still applies:

database row now:           "enterprise"
this object's baseline:     "starter"
this object's current plan: "starter"

From the object’s perspective, plan is unchanged:

account.will_save_change_to_plan?
# => false

That answer is internally consistent. It is not a freshness check.

Now assign another value:

account.plan = "growth"

account.plan_change_to_be_saved
# => ["starter", "growth"]

Rails can accurately describe the change this object proposes relative to its own baseline, even though another process has already changed the row to enterprise.

If the question is what the database contains now, cross the database boundary again:

account.reload

reload does more than check the row. It replaces the object’s attribute state and clears its dirty-tracking comparisons:

account.plan
# => "enterprise"

account.will_save_change_to_plan?
# => false

account.saved_changes
# => {}

Any unsaved growth assignment is gone. The last-save history associated with the old object state is gone too.

Reloading replaces the baseline rather than preserving the old comparison. If application code needs the pending values, it must capture them before reloading or query through a separate object.

Dirty tracking describes one object’s relationship to the database-derived state that object knows. It does not continuously synchronize that relationship with the live row.

Mutable values need their type

Scalar assignment makes the comparison easy to see:

account.plan = "growth"

Suppose settings is backed by a JSON column. Its hash can change without calling the attribute setter:

account.settings["digest"] = "weekly"

For ordinary database-backed attributes, Active Record can detect many in-place changes through its attribute type:

account.will_save_change_to_settings?
# => true

The type API provides changed_in_place? for values changed without assignment. Rails’ JSON type deserializes the original stored JSON and compares it with the current hash. Its string type compares the original stored string with the current string. A custom type that returns a mutable object must provide an equivalent comparison, or Rails may not know that the attribute needs to be written.

Plain ActiveModel::Dirty requires manual marking for in-place mutation.

The debugging question is “what attribute type owns this value, and can it detect the way the value was changed?”

Inspect the right comparison

When a callback, audit, or synchronization path reports the wrong change, inspect the record at the point where the code makes its decision. Ask:

Am I before the save or after it?

Am I asking about the next write or the last completed write?

Am I comparing this object's snapshots,
or do I need fresh database state?

Those questions are more useful than starting with changed?, because they identify the temporal comparison the code needs.

Dirty tracking can describe the proposed write. It cannot tell us whether validations, callbacks, or persistence will allow that write to happen.

That is the work coordinated by save.

A serializer grows one nested field. The review focuses on the JSON shape, not on database access. Staging has five accounts. Every individual query is fast, and the diff ships without drama.

Then a larger customer requests a full page of fifty accounts, and the same response-building loop turns one request into fifty-one query executions.

The code did not add a visible query object. It added object navigation inside a loop.

account = Account.active.limit(50)

accounts.map do |account|
  {
    name: account.name,
    invoices: account.invoices.map do |invoice|
      {
        number: invoice.number,
        status: invoice.status
      }
    end
  }
end

Read it quickly, and it looks like formatting: get the active accounts, include a little invoice data for each one, return an array of hashes.

The SQL log tells a different story. First Rails loads the parents:

SELECT "accounts".*
FROM "accounts"
WHERE "accounts"."active" = TRUE
LIMIT 50

Then the invoice query repeats for one owner at a time:

SELECT "invoices".*
FROM "invoices"
WHERE "invoices"."account_id" = 12

SELECT "invoices".*
FROM "invoices"
WHERE "invoices"."account_id" = 19

SELECT "invoices".*
FROM "invoices"
WHERE "invoices"."account_id" = 27

And so on.

Nothing in the loop looks like a query builder because the query is hidden behind account.invoices. That call uses the same association reader from Associations Are Query Interfaces, Not Object Properties: it feels like a property, but it is a query interface with cache state.

Lazy loading can feel wonderfully convenient for one object; across a collection, the same convenience becomes a scaling rule.

N+1 is not Rails forgetting to be efficient. It is lazy loading repeated across a collection.

Loaded for Which Question?

The misleading assumption is small: I loaded the accounts, so this loop is now memory-only Ruby work.

But the loaded state belongs to a specific object and a specific question.

Before execution, accounts is still a relation. Once the loop begins, Rails has to load that outer relation, but the association targets remain separate:

relation = Account.active.limit(50)

relation.loaded?
# => false

accounts = relation.to_a

relation.loaded?
# => true

accounts.first(3).map do |account|
  account.association(:invoices).loaded?
end
# => [false, false, false]

The parent relation loaded its account records, but it did nothing about the invoice association target on each account.

Those are separate pieces of state:

• relation.loaded? describes the parent relation.

• account.association(:invoices).loaded? describes one owner’s association target.

When the serializer calls account.invoices.map(&:number), the association proxy has to produce invoice records. For one account, that path is reasonable: account.invoices returns a CollectionProxy, Rails sees that the target is unloaded, builds an owner-scoped relation, runs a query for that account ID, and stores the returned rows on that account object’s association target.

Put the same association read inside a loop, and Rails repeats the same lazy-loading path for every owner:

accounts.each do |account|
  account.invoices.map(&:number)
end

The +1 is the parent query. The N is the repeated association query. In this example, one account query is followed by fifty invoice queries.

Each query is fast. The problem is that the query count scales with the parent collection: 50 accounts mean 50 invoice queries, and the endpoint becomes more expensive with every record the page adds.

Nothing changed in the body of the loop. Only the size of the parent collection changed.

Move the Association Load Outside the Loop

If the response needs invoice records for every account, load those records as a set:

accounts = Account
  .active
  .preload(:invoices)
  .limit(50)

accounts.map do |account|
  {
    name: account.name,
    invoices: account.invoices.map do |invoice|
      {
        number: invoice.number,
        status: invoice.status
      }
    end
  }
end

Now Rails can fetch invoices for the parent set instead of asking each owner separately:

SELECT "invoices".*
FROM "invoices"
WHERE "invoices"."account_id" IN (12, 19, 27, ...)

The association targets still belong to individual account objects. Preloading leaves those targets in place; it changes when they are filled. With lazy loading, each owner fills its target when the loop touches it. With preloading, Rails collects the parent IDs, fetches the associated rows using a set-based query, and attaches the correct invoice records to the correct account targets before the loop asks for them.

Rails offers three related loading APIs. preload loads each requested association with a separate query. Internally, ActiveRecord::Associations::Preloader groups owners and assigns the fetched child records back to the correct association targets.

eager_load loads parents and associations through a LEFT OUTER JOIN.

includes normally uses separate queries, but conditions or references involving the associated table can make Rails use a LEFT OUTER JOIN.

The first debugging question is: will this association be loaded once for the parent set, or lazily once per parent object?

Use that question before stopping at includes.

Preloading Has to Match the Question

Preloading associated records fixes repeated record loading. Calls that compose a scoped relation or request a calculation can still go back to SQL.

The first surprise comes from scoped relations. Suppose Invoice defines an unpaid scope:

class Invoice < ApplicationRecord
  scope :unpaid, -> { where(status: "unpaid") }
end

accounts = Account
  .active
  .preload(:invoices)
  .limit(50)

accounts.each do |account|
  account.invoices.unpaid.each do |invoice|
    # ...
  end
end

The base invoices target may be loaded, but account.invoices.unpaid composes a new owner-scoped relation. That relation asks a different database question:

account.invoices
# read the loaded base target

account.invoices.unpaid
# build a scoped relation for unpaid invoices owned by this account

If unpaid invoices are the records the response needs, preload that target directly:

class Account < ApplicationRecord
  has_many :invoices
  has_many :unpaid_invoices, -> { unpaid }, class_name: "Invoice"
end

accounts = Account
  .active
  .preload(:unpaid_invoices)
  .limit(50)

Now the loop can read account.unpaid_invoices as the preloaded association target, instead of composing a new scoped relation from account.invoices.

One caveat: invoices and unpaid_invoices are separate association targets. Preloading one does not populate the other, so preload the association that the loop actually reads.

Counts create a different version of the same mistake:

accounts = Account
  .active
  .preload(:invoices)
  .limit(50)

accounts.map do |account|
  {
    name: account.name,
    invoice_count: account.invoices.count
  }
end

The loop can still issue one count query per account. The code asked a different question.

account.invoices.map needs records, so preloading records helps.

account.invoices.count requests a count from the database. On an association collection, count is an SQL calculation. It does not have to instantiate the target first.

If the target is already loaded and you want the number of loaded records, use the collection-aware method:

account.invoices.size

size can use the loaded target when one is present. It can also use a counter cache or issue a count when the target is not loaded.

The method names look interchangeable in Ruby. They are not interchangeable at the persistence boundary.

Separate the question before choosing the fix:

• Need the preloaded records? Read the association target.

• Need filtered subset? Preload a matching named association or answer it set-wise.

• Need a count? Use a grouped aggregate, a counter cache, or size on an intentionally loaded target.

• Need a boolean? Prefer a set-based existence query over one exists? call per parent.

For counts, a grouped query may be the right shape:

accounts = Account.active.limit(50).to_a
account_ids = accounts.map(&:id)

counts_by_account_id = Invoice
  .where(account_id: account_ids)
  .group(:account_id)
  .count

generating one grouped query for the whole page:

SELECT COUNT(*) AS "count_all", "invoices"."account_id" AS "invoices_account_id"
FROM "invoices"
WHERE "invoices"."account_id" IN (12, 19, 27, ...)
GROUP BY "invoices"."account_id"

Then the loop can read from a hash instead of asking each association for its own account:

accounts.map do |account|
  {
    name: account.name,
    invoice_count: counts_by_account_id[account.id] || 0
  }
end

Booleans follow the same pattern. Instead of one exists? query per account, ask once which parent IDs have invoices at all:

ids_with_invoices = Invoice
  .where(account_id: account_ids)
  .distinct
  .pluck(:account_id)
  .to_set

accounts.map do |account|
  {
    name: account.name,
    has_invoices: ids_with_invoices.include?(account.id)
  }
end

One set-based query answers the existence question for the whole page.

Preload the association when the loop needs records. Choose a different query when the loop needs an answer about those records.

Why This Survives Code Review

N+1 problems survive code review because each line looks reasonable in isolation.

The controller owns the parent relation, such as @accounts = Account.active.limit(50). The serializer owns the association read, such as account.invoices.map.

Neither file says “run one query per account.” The database cost emerges only when those layers execute together.

The controller chooses the parent relation, the serializer decides which associations are touched, and the database sees the combined runtime behavior. In a mature app, that cost may show up far away from the serializer: higher latency, more checked-out connections, or a database that suddenly looks busy even though no single query looks frightening.

Small test fixtures hide it too. With three accounts, the endpoint returns the expected JSON. With a full page of fifty accounts, the same code path can execute fifty-one queries before the application has done anything else interesting.

Detecting and Enforcing the Boundary

The first diagnostic tool is still the SQL log.

Do not read it only as noise. Look for the same query template repeated with a different owner ID: WHERE "invoices"."account_id" = 12, then 19, then 27, and so on. The changing ID is the clue that Rails is loading the same association once per parent.

Then inspect association state for one object:

account = accounts.first

account.association(:invoices).loaded?
# => false

If the code is meant to read preloaded records, that answer matters.

After a successful preload, each parent should have that association target ready:

accounts = Account.active.preload(:invoices).limit(50).to_a

accounts.first.association(:invoices).loaded?
# => true

Rails also gives you a guardrail: strict_loading.

accounts = Account
  .strict_loading
  .active
  .limit(50)
  .to_a

accounts.first.invoices.to_a
# raises ActiveRecord::StrictLoadingViolationError

The trigger is retrieving associated records, not merely to touch the reader. Calling accounts.first.invoices returns the association proxy without complaint. Methods such as to_a, each, and map load the collection target; a finder such as first may issue a narrower association query. Either way, Rails has crossed from returning the proxy to lazily retrieving associated records.

Strict loading is not an explanation of N+1. It is enforcement: it turns unexpected association lazy loading into a visible failure.

The guardrail does not have to stay local to one relation. Setting config.active_record.strict_loading_by_default = true in development makes every relation strict, so a new lazy load fails on your machine instead of on a customer’s page. If raising is too aggressive for an existing codebase, config.active_record.action_on_strict_loading_violation = :log reports violations without breaking requests, which turns cleanup into a backlog you can work through instead of an incident.

Keep the boundary clear. Strict loading governs association lazy loading; it will not explain every repeated query. A loop that calls account.invoices.count is issuing explicit aggregate SQL, so it still needs log reading, query instrumentation, or a different query shape.

The Debugging Reflex

When you see N+1 behavior, do not treat includes as the diagnosis.

Ask what the outer query loaded, which association each parent loaded lazily, and whether the loop needs records, a filtered subset, a count, or a boolean. Then decide whether the associated data should be loaded as a set or the question answered with a different query.

An association reader is not a plain object property. Through the association proxy, the reader can load or read a target, compose a relation, ask SQL for a count, or ask SQL for existence.

Put an operation that needs those records or asks a database question through the association inside a loop, and the distinction becomes visible in the log.

Lazy loading is useful because Rails can wait until the code needs associated records. N+1 is the cost of making that decision one owner at a time.

Loading the right records resolves one boundary. The next confusion begins when changing a Ruby object feels like changing the database.

account.invoices.to_a

The confusion begins once you assume the association has already loaded.

account = Account.includes(:invoices).find(42)

account.invoices.loaded?
# => true

account.invoices.map(&:id)
# no SELECT

account.invoices.overdue.any?
# Invoice Exists?
# SELECT 1 AS one
# FROM "invoices"
# WHERE "invoices"."account_id" = 42
#   AND "invoices"."status" = 'overdue'
# LIMIT 1 

The output looks contradictory only if “the association is loaded” means too much.

Rails loaded one target:

The invoices association for this account

The later line asked a different question:

Does this account have any overdue invoices?

Those are related questions, but they are not the same operation.

A loaded association target does not make every future association-shaped call memory-only.

account.invoices feels intuitive because it looks like object navigation, which is the main goal in typical application code. It allows you to navigate from an account to its invoices effortlessly, without concern for foreign keys, relation builders, or object caches.

But Rails is not storing “the invoices” as a plain property on the Account object.

An association reader is a query interface with cache state.

The Association Declaration Is Metadata

The association begins in the model class:

class Account < ApplicationRecord
  has_many :invoices
end

has_many does not load invoices. It records association metadata: how invoices relate to accounts, which Rails can inspect later:

reflection = Account.reflect_on_association(:invoices)

reflection.macro
# => :has_many

reflection.klass
# => Invoice

reflection.foreign_key
# => "account_id"

The declaration gives class-level information:

Account has many Invoice records
Invoice rows point back through account_id

An individual account supplies instance-level state:

account.id
# => 42

Together, those pieces let Rails build a query for this owner:

account.invoices.scope.to_sql
# => SELECT "invoices".*
#    FROM "invoices"
#    WHERE "invoices"."account_id" = 42

No invoice object has to exist yet.

The association reader packages three pieces:

association declaration
owner object state
association scope

For a collection association, Rails exposes those pieces through a CollectionProxy.

The next operation decides what happens:

build a narrower relation
load the target
read the loaded target
ask SQL for a count or existence answer
construct a new associated object

The Reader Returns an Interface

For a collection association, account.invoices returns an ActiveRecord::Associations::CollectionProxy.

That proxy can behave like a relation:

account.invoices.where(status: "paid")
account.invoices.order(issued_at: :desc)
account.invoices.limit(10)

It can behave like a collection:

account.invoices.each { |invoice| invoice.total_cents }
account.invoices.map(&:id)
account.invoices.length

It can also build new associated objects:

invoice = account.invoices.build(total_cents: 5000)

invoice.account_id
# => 42

Those calls do not take the same path.

account.invoices.count
# SELECT COUNT(*)
# FROM "invoices"
# WHERE "invoices"."account_id" = 42

count asks the database for a number.

account.invoices.each do |invoice|
  invoice.total_cents
end
# SELECT "invoices".*
# FROM "invoices"
# WHERE "invoices"."account_id" = 42

each needs records, so Rails loads the target.

account.invoices.where(status: "paid")
# no SELECT yet

where returns a narrower relation from the association scope.

The same reader can lead to relation composition, SQL, target loading, target reading, or object construction.

Reading account.invoices as “the invoices stored on account” eventually breaks down.

Loading Creates a Target

When Rails loads a collection association, it stores the resulting records as the association target for that owner object.

Before loading:

invoices = account.invoices

invoices.loaded?
# => false

loaded? is only a state check. It does not load the association.

After loading:

invoices.to_a

invoices.loaded?
# => true

Now a plain read can use the loaded target:

account.invoices.loaded?
# => true

account.invoices.map(&:id)
# no additional SELECT for the base association target

That target belongs to this owner object and this association.

first = Account.find(42)
second = Account.find(42)

first.invoices.to_a

first.invoices.loaded?
# => true

second.invoices.loaded?
# => false

Two Ruby objects can represent the same database row yet have different association states. Loading first.invoices leaves second.invoices untouched.

That association target is also separate from Rails’ SQL query cache.

The association cache lives on the model instance. It remembers the loaded target for account.invoices.

The SQL query cache operates at a lower level, storing repeated SQL result sets for a connection within a request or execution context. It may avoid another database round trip for identical SQL, but Rails can still instantiate separate Ruby objects and maintain separate association targets.

When the target is suspicious, inspect the association object:

association = account.association(:invoices)

association.loaded?
# => true

association.target
# => [#<Invoice id: 1, ...>, #<Invoice id: 2, ...>]

target is a diagnostic tool. Application code should rarely need it.

Read it together with loaded? because a target can contain in-memory additions even when the full association has not been loaded.

A Loaded Target Is Not Every Query

Now return to the surprise:

account = Account.includes(:invoices).find(42)

account.invoices.loaded?
# => true

account.invoices.overdue.any?
# SELECT 1 AS one ...

The base target is loaded:

All invoices for the account 42

The scoped association call composes a new query:

overdue invoices for account 42

Rails does not assume that every future scope should filter the loaded array in Ruby. When you chain where, order, limit, or a named scope onto the association proxy, you are usually building a relation from the association scope.

account.invoices.where(status: "overdue").to_sql
# => SELECT "invoices".*
#    FROM "invoices"
#    WHERE "invoices"."account_id" = 42
#      AND "invoices"."status" = 'overdue'

That relation is not the already-loaded target. It is a more specific database question.

If you want to filter the loaded target in Ruby, say that:

account.invoices.select { |invoice| invoice.status == "overdue" }

That uses the loaded records and moves the filtering work into Ruby.

For a small collection already needed by the page, that's fine. For a large collection, the database is usually the better place to filter.

Do not make that a rule that memory or SQL is always better. Know which one you asked for.

select makes this especially easy to blur:

account.invoices.select(:id, :status)

That builds an SQL projection.

account.invoices.select { |invoice| invoice.status == "overdue" }

That loads records and filters them in Ruby.

With arguments, select behaves like a relation builder. With a block, it behaves like Enumerable and needs records.

The same method name spans different execution paths depending on how you call it.

Loaded for Which Question?

account = Account.includes(:invoices).find(42)

account.invoices.size
# uses the loaded target

account.invoices.overdue.any?
# SQL

The query itself is not the issue.

The problem is that the application code treated “the association is loaded” as if it answered every association question the code would later ask.

loaded? tells you whether Rails has loaded a target.

It does not certify future association-shaped calls as memory-only.

With Account.includes(:invoices), the code preloads invoices for this account. The next line asks: "Does this account have overdue invoices?"

Rails took a different path because those questions are different.

This can show up in a view:

<%= account.invoices.size %>

<% if account.invoices.overdue.any? %>
  Overdue
<% end %>

It can show up in a serializer:

class AccountSerializer
  def as_json
    {
      invoice_ids: account.invoices.map(&:id),
      has_overdue_invoices: account.invoices.overdue.any?
    }
  end
end

It can show up in a policy or mailer:

return unless account.invoices.visible_to(user).any?

In each case, the question is the same:

Did this code read the loaded target, or did it build another query?

Choosing the Right Shape

Once you name the question, the fix becomes a design choice instead of a preload ritual.

If the page already needs all invoices and the collection is reasonably small, read the target:

account.invoices.any?(&:overdue?)

If the page needs a scoped collection, model and preload that target:

class Account < ApplicationRecord
  has_many :invoices
  has_many :overdue_invoices,
    -> { overdue },
    class_name: "Invoice"
end

Then, preload the target you plan to read:

account = Account
  .includes(:overdue_invoices)
  .find(42)

account.overdue_invoices.loaded?
# => true

If the page only needs a boolean, ask for it directly, usually through a scope, query object, or database view. Loading another association to answer "yes" or "no" may be the wrong approach.

Be careful with this tempting rewrite:

Account
  .includes(:invoices)
  .where(invoices: { status: "overdue" })

Treat that as more than “the same preload, but filtered.”

Conditions in the included table can move Rails from separate preload queries toward a joined eager-loading shape using LEFT OUTER JOIN. That can change which parent rows appear, which child rows are available through the loaded association, and how much duplicate row data Rails has to process.

It may be the right query, but it is no longer merely a preload decision.

Counts, Existence, and Collection State

Association methods that look similar in Ruby can ask different persistence questions.

Limits, custom scopes, select, distinct, joins, counter caches, and strict loading can still change details.

On an unloaded association, without a usable counter cache, any? and empty? ask existence questions. They do not load the target or run a full count. exists? should be treated as an explicit database check, even when the target is loaded.

size is collection-aware. It can use a loaded target, include built-but-unsaved records, or read a counter cache on the parent. count asks the database.

invoice = account.invoices.build(total_cents: 5000)

account.invoices.size
# includes the built invoice

account.invoices.count
# database count

If Invoice belongs to Account with a counter cache and accounts.invoices_count is present, account.invoices.size can read the count from the already-loaded account instead of issuing SELECT COUNT(*).

Useful, but only as accurate as the counter column. On old tables, failed backfills or manual SQL changes can turn a performance feature into a misleading object state.

When the log feels random, name the operation:

database count
SQL existence check
counter-cache read
target load
target read
new scoped relation
cache reset

Singular Associations Have Cache State Too

Collections make the proxy visible, but singular associations share the same basic shape.

invoice = Invoice.find(123)

invoice.association(:account).loaded?
# => false

invoice.account
# Account Load
# SELECT "accounts".*
# FROM "accounts"
# WHERE "accounts"."id" = 42
# LIMIT 1

invoice.association(:account).loaded?
# => true

After that, invoice.account can return the cached object.

invoice.account.anem
# no additional SELECT for the cached account

The foreign key and the associated object are different state:

invoice.account_id
# => 42

account_id is an attribute on the invoice snapshot. invoice.account is an association read. One is already present on the loaded invoice. The other may need a query and may then be cached.

Bidirectional associations add one more cache wrinkle. Rails can often connect both sides of an ordinary association in memory, so invoice.account may reuse the already-loaded account object. Custom names, foreign keys, through associations, and scopes can make that inverse relationship ambiguous. inverse_of helps Rails stitch both sides of the object graph together once records are in memory. It is not a preload.

Debugging Association State

When association behavior is surprising, separate the four questions:

What relationship did the model declare?
What query would this owner use?
Has this owner loaded this association target?
Is the code reading the target or composing a new query?

For most debugging, the useful handles are small: the association object, the generated scope, the loaded target, and the reset/reload controls.

Start with the association object:

account = Account.find(42)
association = account.association(:invoices)

association.loaded?
# => false

Look at the query shape without loading records:

account.invoices.scope.to_sql

Compare the operations that look similar:

account.invoices.size
account.invoices.length
account.invoices.any?
account.invoices.empty?
account.invoices.exists?
account.invoices.any?(&:overdue?)
account.invoices.overdue.any?
account.invoices.to_a

When lazy loads are expensive, strict_loading can turn an accidental association read into an explicit failure.

account = Account.strict_loading.find(42)
account.invoices.to_a
# raises ActiveRecord::StrictLoadingViolationError

Rails also supports narrower strict-loading modes for N+1 detection:

account.strict_loading!(mode: :n_plus_one_only)

Use that when you want to catch repeated lazy loading across a collection.

Do not treat strict loading as an explanation of association semantics. It is a guardrail. It indicates that the code attempted to load an association through a strict record without loading it in advance. You still need to decide whether the right fix is preloading, a scoped association, or an explicit query defined elsewhere.

The Debugging Reflex

Do not ask only:

Is the association loaded?

Ask:

Loaded for which question?

account.invoices can expose a loaded target.

account.invoices.where(…) can build a new relation.

account.invoices.size can use memory, SQL, or a counter cache depending on state.

account.invoices.reset can discard the target.

invoices.account can be a cached object or a query waiting for the first read.

Associations are what make Rails models feel connected. The cost is that object navigation and query construction can be hidden behind the same method name.

When the same mistaken assumption recurs throughout a collection, the problem grows louder.

N+1 starts there: association lazy loading repeated once per parent record.

invoice = Invoice.find(42)
same_invoice = Invoice.find(42)

same_invoice.update!(status: "paid")

invoice.status
# => "overdue"

same_invoice.status
# => "paid"

invoice == same_invoice
# => true

That last line is the surprise.

Both objects represent the same database row. They have the same model class and the same primary key. Active Record can compare them as the same record.

They are not the same Ruby object, and they do not have to carry the same attribute values.

invoice.equal?(same_invoice)
# => false

The first object did not get a message from the database when the second object saved. It stayed exactly what it was: a Ruby representation of database-backed state as Rails saw it when that object was loaded.

It is not the row.

A loaded Active Record object is not synchronized database truth. It is an in-memory snapshot of the database-backed state at a particular moment.

The last article traced deferred query intent. An ActiveRecord::Relation is not loaded data until something forces execution.

Once execution has happened, the confusion moves from query intent to object state.

From Row to Object

When you call find, Rails does not hand your Ruby process a database row.

It performs a translation.

query intent
    ->
SQL execution
    ->
database result row
    ->
attribute state is built
    ->
model object is instantiated
    ->
Ruby code receives an Active Record instance

The object you receive behaves like the application code wants a domain object to behave.

invoice.id
invoice.status
invoice.due_on
invoice.total_cents
invoice.overdue?

The object came from the database, but after materialization, ordinary attribute reads are object reads.

invoice.status
# no SELECT

Rails already has attribute state for status inside the model instance, backed by Active Record’s type system. It does not need to ask the database again each time you call the method.

Active Record works naturally in controllers, policies, serializers, and views for the same reason stale-object bugs are easy to miss. The syntax does not remind you when the database stopped being involved.

The Snapshot Can Drift

Any other execution path can change the row after your object was loaded.

invoice = Invoice.find(42)
# => #<Invoice id: 42, status: "overdue">

Invoice.where(id: 42).update_all(status: "paid")

invoice.status
# => "overdue"

The update_all call changed the database row. It did not mutate the already-loaded invoice object.

update_all issues a direct database update without instantiating model objects or running the normal record lifecycle.

The same drift can come from another request, a background job, a console session, a webhook handler, a migration script, or a direct SQL statement. Rails does not keep a live subscription between every row and every Ruby object that has ever represented it.

If you want a newer database state, you have to cross the boundary again.

invoice.reload

invoice.status
# => "paid"

reload is not a cosmetic refresh. It is a database read. It discards the object’s current attribute snapshot and replaces it with a fresh one from the row, or raises ActiveRecord::RecordNotFound if the row is gone.

Active Record Identity Is Not Object Identity

Two Rails concepts often get mixed up:

Ruby object identity
  Is this the exact same object allocation?

Active Record identity
  Does this model instance represent the same table row?

They answer different questions.

first_copy = Invoice.find(42)
second_copy = Invoice.find(42)

first_copy.equal?(second_copy)
# => false

first_copy == second_copy
# => true

equal? is Ruby object identity. These are two different objects.

== is Active Record identity. Once a persisted model has a primary key, Active Record can treat another object of the same model and the same primary key as the same record.

New records, records loaded without their primary key, and unusual primary-key setups have edge cases, but the ordinary persisted-record case behaves this way.

The comparison lets sets, arrays, and application code reason about records by database identity rather than by memory address.

But it is not a freshness check.

second_copy.update!(status: "paid")

first_copy.status
# => "overdue"

second_copy.status
# => "paid"

first_copy == second_copy
# => true

No contradiction: two Ruby objects can have the same database identity and different attribute snapshots.

The Query Cache Is Not an Identity Map

Rails has a Query cache, but that does not change the object model.

Within a request or execution context, Rails may cache SQL result sets for repeated identical reads on a connection. The cache can avoid duplicate trips to the database for the same SQL.

It does not mean Rails keeps one live Ruby object per database row.

Invoice.find(42).equal?(Invoice.find(42))
# => false

In ordinary Rails code, separate loads can produce separate objects. Even when a SQL result is cached, Rails can still instantiate model objects from that result. Each instance owns its own attribute state. Updating one instance does not update every other instance with the same primary key.

A method call on invoice reads the invoice’s state. That local ownership keeps Active Record pleasant to work with, but it also means correctness that depends on current database state must be explicit.

The Production Bug

Stale snapshots become production bugs when code makes a later decision from an earlier object.

Consider an overdue reminder job.

class SendOverdueReminderJob < ApplicationJob
  def perform(invoice_id)
    invoice = Invoice.find(invoice_id)

    return unless invoice.overdue?

    InvoiceMailer.overdue(invoice).deliver_now
    invoice.update!(last_reminder_sent_at: Time.current)
  end
end

That code is reasonable in isolation. It loads the invoice, checks whether it is overdue, sends the email, and records that the reminder was sent.

The length of the gap is not the issue. The database read and the Ruby predicate are two separate steps, and another process can commit between them.

Now add production timing:

10:00:00.000  job loads invoice #42 as overdue
10:00:00.050  customer pays invoice #42 in a web request
10:00:00.090  web request updates invoice #42 to paid
10:00:00.140  job checks its already-loaded invoice object
10:00:00.160  job sends an overdue reminder for a paid invoice

The method reads the loaded object.

def overdue?
  status == “overdue”
end

That method does not secretly issue a SELECT. It asks the object for its current status value. If the object was loaded before the payment was completed, the answer can be stale.

Reloading just before the decision can narrow that window:

invoice.reload

return unless invoice.overdue?

But reload is not a concurrency strategy. It narrows one stale-read window; it does not make a read-modify-side-effect sequence automatic. Another process can still change the row after the reload and before the email.

For decisions that must be true at the database boundary, shape the operation as a database question or a database transition.

updated = Invoice
  .where(id: invoice_id, status: "overdue")
  .update_all(
    reminder_state: "queued",
    updated_at: Time.current
  )

return unless updated == 1

invoice = Invoice.find(invoice_id)
InvoiceMailer.overdue(invoice).deliver_now

Here, the database performs the conditional transition rather than using the loaded object’s old status.

A real reminder system may still need an outbox, a transaction, after_commit, locking, idempotency keys, or a state machine.

The job violated one boundary:

invoice.overdue?

It is an object-state question.

Sometimes production code needs a database-state question.

Lifecycle Flags Belong to the Object

Methods like new_record?, persisted?, and destroyed? look like database questions.

They are object-lifecycle questions.

Conceptually, the predicates are close to this:

def new_record?
  @new_record
end

def destroyed?
  @destroyed
end

def persisted?
  !(@new_record || @destroyed)
end

They tell you what this Ruby object believes about its own Active Record lifecycle. They do not perform a fresh database query.

invoice = Invoice.find(42)

Invoice.where(id: 42).delete_all

invoice.persisted?
# => true

invoice.destroyed?
# => false

Invoice.exists?(invoice.id)
# => false

invoice.reload
# raises ActiveRecord::RecordNotFound

The object did not go through destroy. It was not told that another SQL statement had deleted its row. Its flags still describe the lifecycle of the object you are holding.

The same rule applies when the object itself performs the deletion:

invoice = Invoice.find(42)

invoice.destroy!

invoice.destroyed?
# => true

invoice.id
# => 42

Invoice.exists?(invoice.id)
# => false

A destroyed object remains in memory with its ID, which can be useful for logging, auditing, callbacks, and after-commit work.

Do not ask an object-lifecycle predicate to prove current row existence.

Assignment Changes the Object First

Assignment is another place where object state and database state part ways.

invoice = Invoice.find(42)

invoice.status = "paid"

invoice.status
# => "paid"

At this point, no database write has happened.

Dirty tracking describes which attribute changes the next save would persist. For now, the boundary is simpler:

assignment is object mutation
save is persistence orchestration
commit is durable database state

Those steps often appear side by side in Rails code, but they are not the same step. The database only sees writes that actually run, in the order and transaction boundaries it accepts.

reload Replaces the Snapshot

reload is the explicit operation for saying:

discard what this object currently knows
ask the database for this row again
replace this object's attributes with the fresh result

It modifies the receiver in place.

invoice = Invoice.find(42)
object_id = invoice.object_id

invoice.reload

invoice.object_id == object_id
# => true

Existing references still point to the same Ruby object, but that object now carries a new attribute snapshot. Rails also clears related caches around the object, including association cache state.

Repeated reloads often signal that the code is mixing object snapshots and database without naming which one each decision needs.

Use reload when you mean it:

invoice.reload.status

Do not use it as a substitute for deciding where the authority should live.

The View Does Not Make Objects Fresher

Controller instance variables can make loaded records feel more official than they are.

class InvoicesController < ApplicationController
  def show
    @invoice = current_account.invoices.find(params[:id])
  end
end

By the time the view renders, @invoice is a model object carrying an attribute snapshot.

<%= @invoice.status %>
<%= number_to_currency(@invoice.total_cents / 100.0) %>

Those reads do not ask the database again. They read the object.

A render should be internally consistent. If helpers, decorators, serializers, or partials casually reload records during rendering, the page can become a mix of values loaded at different times.

More freshness does not automatically mean more correctness.

A view should behave like a function of the state the controller chose to render. If the view needs reload to make the page correct, the controller or the surrounding workflow loaded the wrong state for the decision being made.

The controller should decide which state it needs, deliberately load that state, and render from it. If a particular decision needs the current database truth, make that query explicit at the boundary instead of hiding reload in the presentation code.

A Debugging Map

When an Active Record object behaves strangely, separate four things:

Ruby object identity
  object_id, equal?

Active Record identity
  model class and primary key

object snapshot
  the values currently held by the model instance

database truth
  what a new database query can observe

Then ask the precise question:

The last row is mostly due to dirty tracking, but the object may contain changes that the database has not yet seen.

Use the answer to choose the next move: inspect the object, reload the object, run a fresh query, or move the decision into a database operation.

Where This Lives in Rails

ActiveRecord::Persistence::ClassMethods#instantiate is part of the path that turns a database result into a model instance. It selects the appropriate class for the record and instantiates it from the returned attributes.

ActiveModel::AttributeSet is part of the typed attribute state beneath ordinary model attribute reads and writes.

ActiveRecord::Core#== explains why two different Ruby objects with the same model class and primary key can compare as equal.

ActiveRecord::Persistence provides lifecycle predicates such as new_record?, persisted?, and destroyed?, as well as reload.

The mental model maps to the implementation:

row returned by SQL
    ->
attribute state built from database values
    ->
model object allocated
    ->
object lifecycle flags initialized
    ->
Ruby object live independently
    ->
another explicit database operation may refresh or persist it

There is no hidden subscription from the database row back to every Ruby object that has represented it.

The Debugging Reflex

Do not start with:

Why is the database wrong?

Ask:

Which snapshot am I reading?

Two model instances can represent the same row and disagree.

Lifecycle predicates can describe the object without proving current row existence.

An assignment can change the object before any write occurs.

reload can replace the snapshot, but it does not make a multi-step operation concurrency-safe.

None of those are edge cases in the framework. They are consequences of the abstraction.

Active Record gives you Ruby objects because Ruby objects are the right interface for application code. The database gives you rows because rows are the durable shared state. Rails translates between them, but it does not collapse them into the same thing.

That sets up the next abstraction.

A loaded model object owns an attribute snapshot. But when you call this:

invoice.line_items

you may not be reading the loaded object state at all.

You may be touching another query interface hidden behind object navigation.

The next boundary is associations: they are not object properties. They are query interfaces with caches. And a loop that reads one of those interfaces lazily, once per record, is how N+1 queries happen.

invoices = current_account.invoices
  .where(status: "overdue")
  .order(due_at: :asc)

That reads like Rails went to the database and fetched overdue invoices.

It did not.

In the ordinary read path, this expression built an ActiveRecord::Relation. It gathered intent: which table, which conditions, which order, which model class should eventually receive the rows. But it did not necessarily send SQL to the database, receive rows, or instantiate Invoice objects.

That difference is easy to miss because Active Record relations are deliberately comfortable. You can chain them like queries, pass them through service objects, return them from scopes, hand them to views, and eventually treat them like collections.

That is the abstraction.

The database work may happen much later than the line where the query was described.

Consider a controller action that wants to show the first fifty overdue invoices:

class Admin::InvoicesController < ApplicationController
  def index
    invoices = current_account.invoices
      .where(status: "overdue")
      .order(due_at: :asc)

    if invoices.present?
      @invoices = invoices.limit(50)
    else
      flash.now[:notice] = "No overdue invoices."
    end
  end
end

This is ordinary Rails code. Nothing looks reckless. The relation is readable. The limit(50) is right there.

Then production traffic finds the account with 80,000 overdue invoices.

The request becomes slow, memory jumps, and the logs show something like this:

Invoice Load (1842.7ms)
  SELECT "invoices".*
  FROM "invoices"
  WHERE "invoices"."account_id" = 42
    AND "invoices"."status" = 'overdue'
  ORDER BY "invoices"."due_at" ASC

Invoice Load (12.8ms)
  SELECT "invoices".*
  FROM "invoices"
  WHERE "invoices"."account_id" = 42
    AND "invoices"."status" = 'overdue'
  ORDER BY "invoices"."due_at" ASC
  LIMIT 50

The expensive query is the innocent-looking empty check:

invoices.present?

present? calls blank?, and for an Active Record relation, blank? needs the relation’s records. That means the relation is loaded. Not counted. Not checked with SELECT 1. Loaded.

The neighboring methods do not all cross the same line:

invoices.blank?   # loads records
invoices.present? # loads records
invoices.empty?   # if loaded, asks an existence question

The problem is not that every collection-looking method is dangerous in the same way. The problem is that each can force the relation to answer a different kind of question.

The guard that was supposed to ask “Is there anything here?” accidentally asked Rails to materialize every matching row before the limited relation was even assigned.

This is the first persistence-boundary mistake.

The Ruby object you are holding is not database truth. It may only be deferred query intent.

Until something forces execution, the relation is just a plan.

A Relation Is Not an Array

We can read Invoice.where(status: “overdue”) as “overdue invoices”, but a more precise reading is “a relation that can later fetch overdue invoices”.

That relation knows enough to become SQL, but it is not yet the result of that SQL.

You can see the difference in a console if you avoid letting the console inspect the relation for you:

relation = Invoice.where(status: "overdue").order(:due_at)

relation.class
# => ActiveRecord::Relation

relation.loaded?
# => false

relation.to_sql
# => SELECT "invoices".* FROM "invoices"
#    WHERE "invoices"."status" = 'overdue'
#    ORDER BY "invoices"."due_at" ASC

relation.loaded?
# => false

to_sql is a great tool for inspecting query shape. It shows the statement Rails has built, but does not run it.

The relation becomes loaded when Rails actually needs records:

records = relation.to_a

relation.loaded?
# => true

records.first
# => #<Invoice id: 1, status: "overdue", ...>

For a record-loading call like to_a, this is the basic lifecycle:

1. relation construction

2. query clauses accumulate

3. an execution method is called

4. SQL is generated

5. the database adapter executes it

6. rows come back

7. model objects are instantiated

8. the relation is marked loaded

Most confusion comes from mentally skipping the first three steps and imagining the relation already contains rows.

The Execution Edges

An Active Record relation crosses into database work when you ask a question that requires database information or records.

The edges are not all the same.

The table is not a replacement for reading logs because details can vary depending on eager loading, limits, grouping, selected columns, and adapter behavior. But it gives you the debugging reflex: do not ask “did I write a query?” Ask “which method forced this relation to answer?”

first, take and find_by are worth separating because they look similar in how they fetch one record, but they do not carry the same ordering meaning. first uses an existing order, or falls back to primary-key order if none is defined. take does not imply application-level ordering. find_by adds conditions, then returns one matching row.

count, size, and length show the same problem from the other direction. They look interchangeable in Ruby, but they are not interchangeable in Active Record.

relation = Invoice.where(status: "overdue")

relation.count
# SELECT COUNT(*) FROM "invoices" WHERE "invoices"."status" = 'overdue'

relation.loaded?
# => false

relation.size
# SELECT COUNT(*) FROM "invoices" WHERE "invoices"."status" = 'overdue'
# because the relation is still unloaded

relation.length
# SELECT "invoices".* FROM "invoices" WHERE "invoices"."status" = 'overdue'
# then instantiate the records

relation.loaded?
# => true

relation.size
# now uses the loaded records

The names are ordinary Ruby names, but the behavior is persistence-boundary behavior.

count asks the database for a number. length needs a loaded Ruby collection. size adapts to the relation’s loaded state.

Some Queries Return Answers Without Loading the Relation

Not every execution turns the relation into loaded model objects.

This is important because otherwise the debugging model becomes too blunt. “Lazy versus loaded” is not the only difference. Sometimes Rails executes SQL and still does not load the relation’s record array.

relation = Invoice.where(status: "overdue")

relation.exists?
# SELECT 1 AS one FROM "invoices"
# WHERE "invoices"."status" = 'overdue'
# LIMIT 1

relation.loaded?
# => false

The database was queried, but the relation is still not loaded.

The same idea applies to calculations and value queries:

relation.count
relation.sum(:total_cents)
relation.pluck(:id)

These execute SQL, but they do not populate the relation’s loaded records. A later iteration can still issue another query for records.

This is a common log pattern:

invoices = Invoice.where(status: "overdue")

Rails.logger.info("Overdue invoice count: #{invoices.count}")

invoices.each do |invoice|
  InvoiceMailer.reminder(invoice).deliver_later
end

The count did not warm the relation:

Invoice Count
  SELECT COUNT(*) FROM "invoices"
  WHERE "invoices"."status" = 'overdue'

Invoice Load
  SELECT "invoices".*
  FROM "invoices"
  WHERE "invoices"."status" = 'overdue'

That may be perfectly acceptable. Sometimes you need both a count and the records. But if you expected one query, the logs look like Rails is doing mysterious extra work.

If you look closely, you’ll notice that you asked two different questions.

One question was “how many rows match this relation?”

The other was “give me model objects for these rows.”

Fix the Empty-State Bug

Return to the original controller:

invoices = current_account.invoices
  .where(status: "overdue")
  .order(due_at: :asc)

if invoices.present?
  @invoices = invoices.limit(50)
else
  flash.now[:notice] = "No overdue invoices."
end

There are a few better versions, depending on what the action really needs.

If the page is going to render the first fifty records anyway, load the page-shaped relation and ask the loaded page whether it is empty:

@invoices = current_account.invoices
  .where(status: "overdue")
  .order(due_at: :asc)
  .limit(50)
  .load

if @invoices.empty?
  flash.now[:notice] = "No overdue invoices."
end

If the branch only needs to know whether anything exists, and you are not about to render the records, ask an existence question:

invoices = current_account.invoices.where(status: "overdue")

if invoices.exists?
  # show a link, schedule work, or continue
else
  flash.now[:notice] = "No overdue invoices."
end

If you need both existence and records, decide whether two queries are acceptable. Sometimes they are. Sometimes it is cleaner to load the limited records once and branch on the loaded result.

The important move is not merely deciding “never use present? on a relation”, though that is a good instinct in many code paths. The important move is naming the state you are holding:

Is this still a deferred query intent?
Did I ask the database for a scalar answer?
Did I load model objects?
Am I reusing the same loaded relation, or have I created a new one?

Those questions turn Active Record from magic into a trace.

A shorter companion note isolates this specific trap: present? and the hidden boundary.

Why Rails Has Relations at All

ActiveRecord::Relation is not only a laziness trick.

It is how Rails lets application code keep describing database work until the final shape of the query is known.

Real Rails queries are rarely born complete. A controller may begin with the current account’s records. A policy may narrow them. A search object may add optional filters. A scope may add business vocabulary. Pagination may add a limit and offset. The view may need preloaded associations. Each layer contributes part of the eventual query.

scope = current_account.invoices
scope = scope.where(status: params[:status]) if params[:status].present?
scope = scope.where("due_at <= ?", params[:due_before]) if params[:due_before].present?
scope = policy_scope(scope)
scope = scope.includes(:customer)
scope = scope.order(due_at: :asc)
scope = scope.limit(50)

If Rails query entry points immediately materialized arrays, every later step would be forced to work with already-loaded Ruby objects. Filtering might happen in memory. Pagination might happen after too many rows had crossed the database boundary. Authorization scopes would have less room to become SQL. Preloading decisions would arrive after the first query had already run.

The relation is the object that keeps those choices open.

It lets Rails say:

not yet
not yet
not yet
now run this final query

That “not yet” is what lets scopes compose:

Invoice.overdue.billable.order(:due_at).limit(50)

It is what lets associations behave like query entry points:

account.invoices.overdue.limit(50)

And it is what lets the same base intent produce different final queries:

overdue = current_account.invoices.where(status: "overdue")

overdue.count
overdue.limit(50)
overdue.pluck(:id)

Those are not three ways of reading the same loaded array. They are three different questions built from the same deferred intent.

A relation lets Rails delay execution because the application has not finished describing the work yet.

Query Method Accumulate Intent

Methods like where, order, limit, select, joins, and named scopes usually keep you in relation-building territory.

base = Invoice.where(status: "overdue")
page = base.order(:due_at).limit(50)
csv  = base.order(:id).select(:id, :number, :total_cents)

These are three different relation objects. They share parts of the same intent, but each one has its own query shape.

The important detail is that chaining does not mutate one loaded collection in place. Active Record relations are composable query objects. A later method usually returns another relation with additional or changed query values.

That is why this code does not load once and then slice in memory:

invoices = Invoice.where(status: "overdue")
page = invoices.limit(50)

The limit belongs to the query plan for page. It is not applied to a Ruby array unless invoices has already been loaded and you explicitly start working with arrays.

Passing a Relation Means Passing Future Work

That composability is useful, but it has an edge: a relation can travel through your application before anyone notices it still represents future database work.

For example, a search object might return a relation instead of records:

class InvoiceSearch
  def initialize(account:, params:)
    @account = account
    @params = params
  end

  def relation
    scope = @account.invoices
    scope = scope.where(status: @params[:status]) if @params[:status].present?
    scope = scope.where("due_at <= ?", @params[:due_before]) if @params[:due_before].present?
    scope.order(due_at: :asc)
  end
end

This object has not hidden database I/O itself. It has hidden query construction, which is a much safer thing to hide.

That is often a good design. It lets the controller decide the final shape:

relation = InvoiceSearch.new(account: current_account, params: params).relation

@invoices = relation.limit(50)

But the risk remains. If a policy, serializer, logging statement, helper, or view calls an execution method before the controller applies pagination or preloading, the query may run with the wrong shape.

A relation is a transportable promise of future database work. Passing a relation around is not passing data around. It is passing a capability to perform database work later.

This becomes especially important once associations enter the picture, because associations often make deferred query intent look like ordinary object navigation:

account.invoices

That expression feels like “the account’s invoices.” In many cases, it is really “a query interface scoped to this account’s invoices.” Read lazily once per record across a whole collection, that interface is also where N+1 queries come from.

The Console Can Add Noise

The Rails console is helpful, but it can teach this topic badly if you trust what appears after pressing enter.

When the console prints a relation, it calls inspection methods so you can see something useful. Rails’ relation inspection may execute a limited query for display. That does not mean where itself eagerly fetched records. It means the console asked the relation to show itself.

Invoice.where(status: "overdue")

If the console immediately prints sample invoices, the display step crossed an execution edge.

When you are checking laziness, assign the relation and ask precise questions:

relation = Invoice.where(status: "overdue")
relation.loaded?
relation.to_sql

Then trigger the edge deliberately:

relation.load
relation.loaded?

That keeps the console from becoming part of the behavior you are trying to understand.

Where This Lives in Rails

The main object here is ActiveRecord::Relation.

A relation carries the model, table, predicate builder, and query values that Rails needs to build SQL. In Rails’ initialization path, a new relation starts out unloaded. The relation can accumulate clauses for a while before records exist.

ActiveRecord::QueryMethods provides much of the chainable query API: where, order, limit, select, joins, includes, and the rest of the vocabulary Rails developers use every day. These methods generally return relations, not arrays.

Relation#to_sql compiles the relation into an SQL string. It is a way to inspect the generated statement.

Relation#load is one of the places where the boundary becomes explicit. If the relation is not loaded, Rails executes the query, stores the resulting records on that relation, and returns the relation itself.

Under that call sits the machinery that turns relation intent into database work: Arel represents the query structure, the adapter compiles and executes SQL appropriate for the database, rows return from the database, and Active Record instantiates model objects from those rows.

You do not need to think about Arel every time you write a scope. But it is useful to know that where(status: “overdue”) is not a string being glued onto a future SQL statement. Rails is building a query representation that the adapter can later compile.

These three tell you what Rails plans to run, whether this relation has records, and when you intentionally cross the boundary:

relation.to_sql
relation.loaded?
relation.load

The Debugging Reflex

When a request performs unexpected database work, do not start by asking whether Active Record is slow.

Start with the execution edge.

A practical trace looks like this:

relation = current_account.invoices.where(status: "overdue")

Rails.logger.info(relation.to_sql)
Rails.logger.info("loaded before? #{relation.loaded?}")

page = relation.limit(50).load

Rails.logger.info("loaded after? #{page.loaded?}")

Then compare that trace with the SQL logs.

If a query appears earlier than expected, search for collection-like calls:

each
map
to_a
as_json
blank?
present?
empty?
length
first
take
find_by
count
exists?
pluck

Some of those load records. Some execute scalar queries. Some instantiate model objects. Some do not. The point is to stop treating them as equivalent Ruby collection methods once the receiver is an ActiveRecord::Relation.

The useful debugging question is:

Am I still holding a deferred query intent, or did something already force database work?

Once the query runs, Rails crosses into the next state. It has rows from the database and turns them into model instances. Those objects feel like rows, but they are not rows either. They are Ruby snapshots of database-backed state, loaded at a particular moment, capable of drifting away from the database as soon as time and other writers move on.

That is the next persistence-boundary mistake: once records are loaded, the confusion moves from query intent to object state.

This page is the map.

The publication is organized as a sequence of chapters. Each chapter follows one boundary in Rails far enough to explain where its behavior comes from, which objects own it, and what to inspect when the abstraction starts leaking in production.

You do not need to read every article in order. Each one answers a specific question and stands on its own. But the sequence matters: later chapters build on distinctions established earlier.

Chapter 1: The Request Boundary

A Rails request does not jump from a URL into a controller action.

It passes through Rack, middleware, routing, controller dispatch, parameter assembly, callbacks, response construction, and view lookup. Chapter 1 follows that path from the outside in.

Its debugging reflex is:

Which request layer owns this behavior?

1. From Rack to Controller: Understanding the Rails Request Lifecycle

2. Inside the Rails Middleware Stack

3. How Rails Routing Works: Turning URLs into Controller Actions

4. How Rails Dispatches a Request to a Controller

5. How Rails Builds params Before Your Action Runs

6. Why Rails Runs Code Before Your Controller Action

7. How Rails Turns a Controller Action Into a Response

8. How Rails Finds the View to Render

Chapter 2: State, Identity, and the Shape Between Requests

HTTP requests are independent, but Rails applications need login state, redirect messages, and authenticated identity to feel continuous.

Chapter 2 examines what actually crosses the request boundary, what Rails reconstructs for each request, and what must be cleared before an execution context is reused.

Its debugging reflex is:

What survived the request boundary, and where was identity reconstructed?

9. Sessions Are Not Server Memory

10. How Rails Flash Survives One Redirect

11. Where Does current_user Actually Live?

Chapter 3: The Persistence Boundary

Chapter 3 moves to the boundary between Ruby intent and database truth.

Active Record makes query construction, object navigation, in-memory changes, and persistent writes feel like one continuous object-oriented interface. They are not a single state, and they do not offer the same guarantees.

In chapter 3, we trace deferred queries, model snapshots, associations, N+1 queries, dirty tracking, saves, transactions, commit callbacks, direct persistence APIs, and database constraints.

Its debugging reflex is:

Am I examining a deferred query, a Ruby object, an uncommitted transaction, or a durable database state?

12. When Does an Active Record Query Actually Run?

13. An Active Record Object Is a Snapshot, Not the Row

14. Associations Are Query Interfaces, Not Object Properties

15. Why N+1 Queries Are a Natural Result of Lazy Loading

16. How Rails Knows What Changed

17. What Happens When You Call save

Where Should You Begin?

If you want the full path, begin with the Rails request lifecycle and read forward.

If you want one representative article first, read How Rails Routing Works. Routing is where an incoming HTTP request first becomes recognizable as Rails application behavior, and the article captures the publication’s mix of execution flow, implementation detail, and practical debugging.

If your current problem is request-to-request state or authentication, begin with Sessions Are Not Server Memory or Where Does current_user Actually Live?.

RailsRevelry is not about memorizing framework source code.

It is about learning to locate behavior: which layer owns it, which state is real, and which boundary your debugging has crossed.

current_user

Controllers branch on it, views render navigation from it, authorization policies depend on it, audit trails often assume it, and service objects sometimes reach for Current.user as if authenticated identity were ambient process state.

The method reads like a global lookup, but a threaded Rails server cannot afford global identity. Puma may run many requests in the same process at the same time. A thread that handled one user’s request a moment ago may handle someone else’s request next. If current_user were merely “the user stored somewhere nearby”, Rails applications would leak identity across requests under ordinary production traffic.

The useful question is not only where the helper is defined, but also which object owns the authenticated identity at each layer of execution, what survives between requests, what is reconstructed for each request, and what gets cleared before the execution context is reused.

In a Devise-backed application, the chain looks like this:

between requests
  the session carries a serialized authentication key

inside Rack
  env["warden"] points to a request-local Warden::Proxy

inside Warden
  the proxy deserializes and memoizes users by scope

inside Action Controller
  Devise exposes current_user and memoizes it on the controller

inside application code
  Current may mirror selected request-wide attributes

after execution
  executor completion callbacks clear CurrentAttributes

The Common Misread

The comfortable mental model is:

current_user
# => the logged-in user

That is useful shorthand for day-to-day controller code, but it hides the parts of the system that matter for concurrency. A more precise model should be:

current_user
# => the authenticated user for this request and scope,
#    reconstructed from request/session state,
#    cached along the request path,
#    and unavailable once the request boundary is gone

The word “current” does not mean “current” in the Ruby process. It means current to an execution context, usually the HTTP request currently being handled by one controller instance, and the boundary becomes visible as soon as code leaves the request path:

class ExportsController < ApplicationController
  def create
    ExportReportJob.perform_later(params[:report_id])

    redirect_to exports_path, notice: "Export started"
  end
end

If the job reaches back into request-local identity, the code has smuggled a controller assumption into a process that has no browser request:

class ExportReportJob < ApplicationJob
  def perform(report_id)
    report = Current.user.reports.find(report_id)

    report.generate!
  end
end

Inline job execution in tests can mask this bug because the job may run before the request context has been torn down. A real queue worker has no controller instance, no request env, no browser cookie, and no authentication callback that just executed. The durable value crossing that boundary should be a small identifier, and the worker should resolve authorization again where the work runs.

class ExportsController < ApplicationController
  def create
    ExportReportJob.perform_later(params[:report_id], current_user.id)

    redirect_to exports_path, notice: "Export started"
  end
end

class ExportReportJob < ApplicationJob
  def perform(report_id, user_id)
    user = User.find(user_id)
    report = user.reports.find(report_id)

    ExportReport.call(report:, actor: user)
  end
end

The job starts a new execution with explicit inputs rather than continuing the request, using the same boundary pattern Rails uses internally: carry a compact identity pointer across the boundary, then resolve the live record in the context where the work happens.

The Ownership Chain

Let’s start with a request path before looking at any helper method:

Browser
  |
  |  Cookie: _app_session=...
  v

Rack env
  |
  |  HTTP headers, path, method, body, cookies
  v

ActionDispatch session middleware
  |
  |  loads session data into env["rack.session"]
  v

Warden::Manager middleware
  |
  |  env["warden"] = Warden::Proxy.new(env, manager)
  |  no user object is loaded just because the proxy exists
  v

Rails router and controller dispatch
  |
  |  before_action :authenticate_user!
  |  current_user -> warden.authenticate(scope: :user)
  v

Warden::Proxy
  |
  |  checks its per-request @users cache
  |  fetches "warden.user.user.key" from the Rack session when needed
  |  deserializes the key into a User record
  v

ActionController instance
  |
  |  Devise helper memoizes @current_user for this controller instance
  |  helper_method exposes the same controller method to views
  v

Current, if the app uses it
  |
  |  Current.user = current_user
  |  Rails isolated execution state stores the request context
  v

Rails Executor completion
  |
  |  executor completion callbacks clear CurrentAttributes
  |  Rails execution context is unwound
  v

The thread returns to the pool without carrying this request's Current state.

Some requests will not traverse this entire path. In many production deployments, a CDN, reverse proxy, web server, or Rack server can serve static files before Rails is involved. In development, test, or application-served file paths, more requests may pass through the Rails stack. The architecture to keep in mind is not “every asset request loads a user”; it is “Warden installs a request-local proxy lazily, and user materialization only happens when application code asks for identity”, which is why the env[“warden”] proxy can exist on a request without making a database query.

The Session Carries a Pointer

A basic custom authentication flow shows the same lifecycle without involving Devise:

class SessionsController < ApplicationController
  def create
    if user = User.authenticate_by(params.permit(:email_address, :password))
      reset_session
      session[:user_id] = user.id

      redirect_to dashboard_path
    else
      redirect_to new_session_path, alert: "Try another email or password."
    end
  end
end

The session stores this:

session[:user_id] = user.id

It does not store this:

session[:user] = user

We traced the default CookieStore pipeline in detail earlier; here, the important part is the object boundary: the browser does not bring a Ruby object back to Rails. It brings headers and cookies. Rails loads session data from those cookies or from whatever session store the application uses. The application then decides whether the identity pointer still resolves to a valid server-side user.

A small hand-rolled helper makes that lifecycle visible:

class ApplicationController < ActionController::Base
  helper_method :current_user

  private

    def current_user
      return @current_user if defined?(@current_user)

      @current_user = User.active.find_by(id: session[:user_id])
    end
end

This method performs three separate jobs:

1. read the identity pointer from the session

2. query the current server-side record

3. memoize the result on this controller instance

The defined?(@current_user) guard is deliberate. It caches nil as well as a user record, so an authenticated request does not repeat the same lookup every time a layout, partial, or policy asks for the user.

Every request repeats the reconstruction, and that repetition is not a wasteful ceremony. It is where the browser’s claim meets the database’s current truth: a user may have been deleted, locked, disabled, removed from an account, or forced through a password reset since the cookie was issued. The request boundary is where stale identity is either accepted, rejected, or downgraded.

The durable value is session[:user_id], while the request-local value is @current_user, and the authentication code becomes hard to reason about when those two lifetimes are treated as the same kind of state.

What Devise Adds

Devise keeps the same lifecycle, but delegates most of the Rack-level work to Warden.

Warden is Rack middleware whose manager receives the Rack env, creates a proxy for the request, and stores it where downstream code can find it.1

# Conceptual shape of Warden::Manager
def call(env)
  env["warden"] = Warden::Proxy.new(env, self)

  @app.call(env)
end

That proxy is stateful, but only for this request:

# Conceptual shape of Warden::Proxy initialization
def initialize(env, manager)
  @env = env
  @manager = manager
  @users = {}
end

The proxy has access to the Rack session through env[“rack.session”]. Warden’s session serializer stores authentication data under a scope-specific key.2

def key_for(scope)
  "warden.user.#{scope}.key"
end

For the default Devise user scope, the session key is:

warden.user.user.key

The value stored there is a compact serialized authentication key, not the Active Record object. Devise’s serializer can later turn that key back into a model record, and the exact serialized shape depends on its mapping and serializer configuration.

When the application code asks Warden for a user, Warden first checks the proxy’s per-request cache. If nothing has been loaded for that scope, it fetches from the session serializer and memoizes the deserialized user on the proxy.3

# Simplified from Warden::Proxy#user
def user(scope)
  return @users[scope] if @users.key?(scope)

  if user = session_serializer.fetch(scope)
    @users[scope] = set_user(user, scope: scope, event: :fetch)
  end
end

Authentication methods such as authenticate and authenticate! can go further: if a session-backed user is not already available, they may run configured strategies and trigger failure behavior. In middleware and telemetry code, the difference between user as an identity fetch and authenticate! as an authentication operation is not cosmetic.

Devise exposes this through controller helpers. The generated helper roughly looks like this. 4

def warden
  request.env["warden"] || raise Devise::MissingWarden
end

def current_user
  @current_user ||= warden.authenticate(scope: :user)
end

There are two caches in play after the first successful lookup:

Warden::Proxy @users[:user]
  per-request Rack authentication cache

ApplicationController @current_user
  per-controller-instance helper cache

Neither cache is the login or survives the request; both are short-lived Ruby objects built from request-backed state.

The View Gets a Bridge

current_user feels more ambient than it is because views can call it.

In a custom implementation, the bridge is usually explicit:

helper_method :current_user

Rails’ helper_method exposes selected controller methods to the view context. Devise registers its mapping helpers in the same spirit, so this layout code:

<% if current_user %>
  <%= link_to current_user.email_address, account_path %>
<% end %>

is still calling a controller helper for the current request. The view has gained a method bridge back into the controller/request context, not access to global authentication state.

That is why the same method is not available in jobs, mailers invoked outside a request, raw model code, concise sessions, and arbitrary threads. Those execution contexts do not have the controller helper bridge unless the application explicitly builds one.

Current Is a Mirror, Not the Source

At some point, a mature Rails codebase usually wants identity deeper than controllers: audit logs need an actor, multi-tenant models need an account, service objects need request metadata, and passing five arguments through every call can become noisy. Rails provides ActiveSupport::CurrentAttributes for that narrow category of request-wide state.

A robust Current class should be small and boring:

# app/models/current.rb
class Current < ActiveSupport::CurrentAttributes
  attribute :user, :account
  attribute :request_id, :ip_address, :user_agent

  resets { Time.zone = nil }

  def user=(user)
    super
    Time.zone = user&.time_zone
  end
end

Then a controller explicitly bridges authenticated identity into request-wide application context:

class ApplicationController < ActionController::Base
  before_action :authenticate_user!
  before_action :set_current_context

  private

    def set_current_context
      Current.user = current_user
      Current.request_id = request.uuid
      Current.ip_address = request.ip
      Current.user_agent = request.user_agent
    end
end

Current.user = current_user doesn’t explain where current_user came from. It copies the already-authenticated request user into Rails’ current execution context. If the authentication layer does not run, or the controller does not perform the bridge, Current.user is not populated by virtue of the class existing.

The Rails API documentation for CurrentAttributes is intentionally cautious: Current should hold only a few top-level globals, such as account, user, and request details, that are used across most actions. Controller-specific state does not belong there because it turns ordinary method calls into hidden dependencies on request context.

In practice, Current is good for values like:

Current.user
Current.account
Current.request_id
Current.ip_address
Current.user_agent

It is a poor home for values like:

Current.invoice
Current.search_query
Current.checkout_step
Current.feature_flag_override_for_this_one_action

Those may be legitimate values, but they are not part of the application-wide request context. A useful test: if the value only makes sense for one controller action, it probably doesn’t belong in Current. It belongs in arguments, query objects, form objects, policy context, or explicit service input.

Isolation and Teardown

The old version of this pattern was usually something like Thread.current[:user] = current_user. It works until it doesn’t, and the failure mode is ugly because web server threads are pooled. If a thread finishes one request and the application forgets to clear the thread local, the next request handled by that thread can observe stale identity.

CurrentAttributes gives a safer primitive, but the important property is lifecycle ownership, not the class name.

Rails describes CurrentAttributes as a thread-isolated attributes singleton that resets automatically before and after each request. In current Rails, the implementation goes through ActiveSupport::IsolatedExecutionState, which supports both :thread and :fiber isolation levels and defaults to :thread unless the application configures a different isolation level.5

config.active_support.isolation_level = :fiber

The precise idea is not “Current is Fiber-local” for every modern Rails application, though. The safer idea is that Current stores attributes in Rails’ isolated execution state, whose locality is configurable, and Rails clears that state through executor lifecycle hooks at the application boundary.

The Rails Executor is the wrapper around application code. The Rails Threading and Code Execution guide describes it as the boundary between framework code and your own code, with to_run callbacks before application execution and to_complete callbacks afterward. In current Rails, Active Support’s railtie wires execution context and current attributes into that lifecycle.6

# Conceptual shape from ActiveSupport::Railtie
app.executor.to_run do
  ActiveSupport::ExecutionContext.push
end

app.executor.to_complete do
  ActiveSupport::CurrentAttributes.clear_all
  ActiveSupport::ExecutionContext.pop
end

Rails wraps ordinary web requests for you, and framework-managed job execution is also run through Rails execution wrappers. The place that hurts is custom concurrency:

Thread.new do
  do_work_that_touches_models_and_current
end

The Rails guide is explicit about manual threads and Concurrent Ruby thread pools: wrap application code with the executor as soon as the thread begins running application work.

Thread.new do
  Rails.application.executor.wrap do
    do_work_that_touches_models_and_current
  end
end

That wrapper is not only about Current.user. It also protects query cache lifetime, connection pool handling, autoload/reload safety, execution context, and other framework-owned state that should not bleed across application executions.

Failure Mode: Current.user as Invisible Job Input

This is the most common production bug because the code can look clean:

class ExportReport
  def self.call(report_id)
    report = Current.user.reports.find(report_id)
    report.generate!
  end
end

The controller path works:

ExportReport.call(params[:report_id])

Then a background job reuses the same service:

class ExportReportJob < ApplicationJob
  def perform(report_id)
    ExportReport.call(report_id)
  end
end

The service has hidden its real dependency. It needs an actor, but the method signature says it only needs a report ID. Inline execution, request specs, and happy-path manual tests may all pass because Current.user happens to be set by the surrounding request. A real worker exposes the truth: the service depends on the request-local state that the job doesn’t have.

The stronger interface makes the actor explicit:

class ExportReport
  def self.call(report_id, actor:)
    report = actor.reports.find(report_id)
    report.generate!
  end
end

class ExportReportJob < ApplicationJob
  def perform(report_id, user_id)
    actor = User.find(user_id)

    ExportReport.call(report_id, actor:)
  end
end

The lookup is also the authorization boundary: the job finds the report through the actor, not through a global report ID.

If a legacy subsystem genuinely expects Current, set it in the narrowest possible block rather than letting it become invisible job state:

class ExportReportJob < ApplicationJob
  def perform(report_id, user_id)
    actor = User.find(user_id)

    Current.set(user: actor) do
      ExportReport.call(report_id)
    end
  end
end

The block form shows the boundary and also gives Rails scope for restoring previous Current values.

Failure Mode: Tenant Context Derived From the Wrong Layer

Rails’ own CurrentAttributes example shows a user= setter that assigns account from user.account. That is reasonable for applications where every user has exactly one account and identity implies tenancy.

It becomes wrong in applications with account switching, delegated access, organization membership, impersonation, or admin consoles.

class Current < ActiveSupport::CurrentAttributes
  attribute :user, :account

  def user=(user)
    super
    self.account = user.account
  end
end

The bug is not that Current.account exists; the bug is encoding a product assumption into the identity setter. In a multi-account system, the authenticated actor and the selected tenant are related but not identical. One answers “who is acting?” while the other answers “within which account boundary is this action authorized?”

Keep those assignments separate:

class ApplicationController < ActionController::Base
  before_action :authenticate_user!
  before_action :set_current_context

  private

    def set_current_context
      account = current_user.accounts.find_by!(slug: params[:account_slug])

      authorize_account_access!(current_user, account)

      Current.user = current_user
      Current.account = account
    end
end

Tenant selection should come from the request, route, subdomain, account switcher, or an explicit policy, and then be authorized against the actor. Deriving it blindly from Current.user is how a convenient default turns into a cross-tenant data bug.

Failure Mode: Middleware Forces Identity Too Early

Middleware is the wrong place for casual identity access because middleware operates before the controller's intent is known.

This looks harmless in telemetry, rate limiting, or request logging code:

class RequestTelemetry
  def initialize(app)
    @app = app
  end

  def call(env)
    user = env["warden"]&.authenticate(scope: :user)

    tag_request(user_id: user&.id)

    @app.call(env)
  end
end

The problem is not only performance. authenticate is allowed to run strategies and invoke authentication failure behavior, so telemetry code can accidentally become authentication code. Even env[“warden”].user(:user) can materialize a database-backed user from the session. If this middleware runs on every request that reaches the Rails stack, the application has expanded “load the user when a controller needs it” into “load the user before routing for broad classes of requests.”

On some deployments, static files and health checks may never reach this middleware. On others, development asset requests, app-served files, engine routes, internal probes, or unauthenticated endpoints may pass through it. The exact blast radius depends on the stack. Still, the architectural smell is stable: a low-level Rack component is forcing high-level identity resolution without knowing whether the endpoint needs a user.

Prefer one of these:

# Use request-level identifiers that do not materialize a User record.
request = ActionDispatch::Request.new(env)
tag_request(
  request_id: request.request_id,
  ip: request.ip
)

or, when authenticated identity is a deliberate requirement, constrain both placement and scope:

def call(env)
  request = ActionDispatch::Request.new(env)

  return @app.call(env) unless request.path.start_with?("/app/")

  if warden = env["warden"]
    user = warden.user(:user) # still a materialization point
    tag_request(user_id: user&.id)
  end

  @app.call(env)
end

That code is not “free” because warden.user(:user) may deserialize from the session and hit the database. The improvement is that the middleware no longer invokes the full authentication flow for every request, and the path restriction makes the cost and behavior intentional.

A Debugging Checklist

When current_user behaves strangely, locate the failing code in the lifecycle before changing authentication logic.

• Execution context: Is this code running inside a controller/view request, middleware, job, console, callback, or manual thread?

• Session layer: Did the request pass through session middleware, and is env[“rack.session”] available?

• Fetch path: Is the user coming from Warden’s per-request @users cache, from session deserialization, or from a strategy?

• Current bridge: Is Current being read inside an executor-wrapped application execution?

• Hidden dependency: Is a service object hiding actor or tenant dependencies behind Current?

• Actor vs. tenant: Are actor identity and tenant/account selection being resolved as separate concepts?

Most confusing authentication bugs become smaller once you name the layer that owns the value and the boundary that should have cleared, copied, or reconstructed it.

Where It Actually Lives

Between requests, the durable authentication reference lives in the session, usually as a compact serialized key carried by a cookie-backed or server-backed session store.

During Rack execution, Devise-backed applications find the authentication interface at env[“warden”], a request-local Warden::Proxy created by Warden middleware.

During authentication, Warden deserializes the scoped session key and memoizes the resulting user object in the proxy’s @users hash.

Inside the controller, Devise exposes current_user as a helper and memoizes it on the controller instance, commonly as @current_user.

Inside deeper application code, Current.user may hold a copy of that identity, but only if the controller or framework code explicitly placed it there for the current execution context.

After execution completes, Rails clears CurrentAttributes and unwinds the execution context through the Executor, so the thread- or fiber-local execution state does not become the next request’s identity.

The method feels like a single answer because Rails and Devise make the handoffs smooth. In production, it is a series of scoped owners with different lifetimes.

The debugging reflex is to treat strange current_user behavior as a lifecycle question, not just a helper return value question. Ask which layer reconstructed the identity, which scope cached it, which execution context copied it, and whether the code has crossed the boundary where “current” stopped meaning anything.

A form submission fails validation, so the controller renders the form again:

class BillingProfilesController < ApplicationController
  def create
    @billing_profile = current_account.billing_profiles.new(billing_profile_params)

    if @billing_profile.save
      redirect_to billing_profile_path(@billing_profile), notice: "Billing profile saved"
    else
      flash[:alert] = @billing_profile.errors.full_messages.to_sentence
      render :new, status: :unprocessable_entity
    end
  end
end

The alert appears on the rendered form, and that part looks fine.

Then the user fixes the form, submits again, and lands on the success page. The old validation message appears there too.

Nothing about the view is obviously wrong. The layout is just rendering flash[:alert] if one exists. The controller assigned the alert only on the failure path. The successful request did not set it.

The bug originates from an underlying assumption that flash is not a view-level message store.

Flash is a request-to-request state. In a default browser-oriented Rails app, it rides through the session. It is built for the response after a redirect, not for every place you want to show a message.

That is why this line is wrong with render:

flash[:alert] = @billing_profile.errors.full_messages.to_sentence

and this line is usually right:

flash.now[:alert] = @billing_profile.errors.full_messages.to_sentence

The difference is not cosmetic. One message is being prepared for a future request. The other belongs only to the current response.

Redirects Need a Handoff

Start with a successful branch:

redirect_to billing_profile_path(@billing_profile), notice: "Billing profile saved."

That code is to do two things at once:

send the browser somewhere else
show a message after it gets there

A redirect does not render the target page. It sends a response with a redirect status and a Location header. The browser then makes a second HTTP request to the new URL.

That means the success message cannot live in the controller instance. The controller instance is gone when the next request starts. It cannot live in an instance variable either:

@notice = "Billing profile saved."
redirect_to billing_profile_path(@billing_profile)

The next request will be handled by a new controller object, which will not know about @notice.

The flash exists to bridge exactly that gap.

POST /billing_profiles
  ->
set flash notice
  ->
redirect response
  ->
GET /billing_profiles/42
  ->
Read flash notice
  ->
discard it

It is a one-request handoff.

Flash Is Session-Backed State

Rails exposes flash through the controller, but the flash lifecycle runs below the controller.

In ActionController::Flash, Rails delegates flash to the request:

delegate :flash, to: request

When Rails needs the flash for a request, the flash methods mixed into the request by ActionDispatch::Flash build a FlashHash from session[“flash”]:

def flash
  flash = flash_hash
  return flash if flash
  self.flash = Flash::FlashHash.from_session_value(session["flash"])
end

The previous article tracked where session data goes. Flash uses that same path under a specific key:

session["flash"]

Flash is not a separate server memory. It is a temporary state stored through the same session machinery.

During request cleanup, Rails commits the flash back into the session.

Rails writes a session-friendly flash value into the session[“flash”], and an empty flash becomes nil, which lets Rails delete the session key.

def commit_flash
  return unless session.enabled?

  if flash_hash && (flash_hash.present? || session.key?("flash"))
    session["flash"] = flash_hash.to_session_value
    self.flash = flash_hash.dup
  end

  if session.loaded? && session.key?("flash") && session["flash"].nil?
    session.delete("flash")
  end
end 

That is the mechanism behind the everyday API:

flash[:notice] = "Saved"
redirect_to account_path

The controller writes to flash. Rails writes a session-friendly flash value into the session[“flash”] when the request finishes. The next request rebuilds a FlashHash from that session entry.

If the session store is CookieStore, the flash is part of the encrypted cookie payload. This is why a large flash message can trigger the same CookieOverflow class of failures as any other oversized session value.

Why Flash Disappears

The strange part of Flash is not that it survives a redirect.

The more interesting part is that it disappears afterward.

If Rails only stored the message hash:

session["flash"] = { "notice" => "Saved" }

Then the notice would appear forever until something removed it.

Rails needs one more bit of information: which entries are being carried into the next request, and which entries have already had their turn.

When you set a flash and redirect, Rails can serialize it like this:

session["flash"] = {
  "discard" = [],
  "flashes" => { "notice" => "Saved" }
}

The empty discard list tells Rails to keep the message for the next request.

On that next request, Rails rebuilds the FlashHash from the session:

new(flashes, flahes.keys)

That second argument becomes the discard set.

So the message is visible, but it is already marked for drop when the request finishes.

def create
  redirect_to dashboard_path, notice: "Welcome back"
end

The next request can read:

<% if flash[:notice] %>
  <p><%= flash[:notice] %></p>
<% end %>

When the request finishes, Rails asks the flash what should survive:

flashes_to_keep = @flashes.except(*@discard)
return nil if flashes_to_keep.empty?

For a normal one-redirect flash, nothing is left to keep. to_session_value returns nil, and commit_flash removes session[“flash”].

The flash is not time-based. It does not expire after some seconds. It survives one request transition because Rails records it in the session, then declines to keep it on subsequent requests.

Render Stays Inside the Same Request

Now return to the original bug:

if @billing_profile.save
  redirect_to billing_profile_path(@billing_profile), notice: "Billing profile saved"
else
  flash[:alert] = @billing_profile.errors.full_messages.to_sentence
  render :new, status: :unprocessable_entity
end

The failure branch does not redirect.

It renders a response inside the same request:

POST /billing_profiles
  ->
validation fails
  ->
render :new
  ->
response returns

There is no second request that needs a handoff.

When you use flash[:alert], Rails assumes you want the message available to the next request. The current response can still render it because the flash is available now, but Rails also prepares it for later.

That is why it can leak into the success page.

For a render, use flash.now:

if @billing_profile.save
  redirect_to billing_profile_path(@billing_profile), notice: "Billing profile saved"
else
  flash.now[:alert] = @billing_profile.errors.full_messages.to_sentence
  render :new, status: :unprocessable_entity
end

flash.now writes the message into the current flash and immediately marks it for discard:

def []=(k, v)
  k = k.to_s
  @flash[k] = v
  @flash.discard(k)
end

The view can render the message in this response. Rails will not carry it forward.

That is the rule:

redirect -> flash
render   -> flash.now

Not because one is more correct in the abstract, but because they have different request lifetimes.

The same rule applies when the response is not a full-page render.

In a Rails 7 app, a failed form submission may return a Turbo Stream or Turbo Frame response instead of rendering the whole layout:

def create
  if @billing_profile.save
    redirect_to billing_profile_path(@billing_profile), notice: "Billing profile saved"
  else
    flash.now[:alert] = "Validation failed"
    render turbo_stream: turbo_stream.replace("billing_form", partial: "form")
  end
end

Turbo changes how the response is delivered. It does not create a follow-up request for the flash to survive. If no redirect is involved, flash.now is usually the safer default.

Keep and Discard

Most application code does not need to call flash.keep or flash.discard directly.

But they explain the lifecycle.

discard marks entries to be removed when the request finishes:

flash.discard(:notice)

keep does the opposite. It tells Rails to carry an entry forward one more time:

flash.keep(:notice)

That can be useful when a request receives a flash and redirects again before the user sees the final page:

POST /signup
  ->
flash[:notice] = "Finish billing setup"
  -> 
redirect_to dashboard_path

GET /dashboard
  ->
notice is available here
  ->
dashboard redirects again
  ->
flash.keep(:notice)

GET /billing/settings
  ->
The notice is still available.

The middle action has to preserve the message deliberately:

def dashboard
  unless current_account.billing_enabled?
    flash.keep(:notice)
    redirect_to billing_settings_path
  end
end

Without keep, the notice is available to /dashboard and then dropped. The second redirect would land on billing settings with no message.

That is the same lifecycle rule, just extended:

loaded flash entries are on their last request
keep extends them
discard shortens them
flash.now never crosses into the next request

Concurrent Requests Can Consume Flash

The clean sequence is easy to picture:

POST
  ->
redirect
  ->
GET target page
  ->
read flash

Production browsers are not always that quiet.

Suppose the app has a background request polling for unread notifications. If that request hits the server after the POST commits the flash but before the browser finishes the redirect, it can load the same session.

If that background request loads the flash and completes its own request lifecycle first, Rails can treat the flash as having been exposed there. The target page may then arrive with no message left to show.

This is not a reason to avoid flash. It is a reason to keep API and background endpoints away from flash unless they intentionally participate in the page flow. In larger apps, that often means isolating JSON endpoints under controllers that do not use the browser session stack, or at least making sure they do not render shared layout code that reads flash.

If a request receives a flash and redirects again, use flash.keep deliberately.

The Production Version

Flash bugs often look like view bugs.

An alert appears on the wrong page. A notice disappears after an extra redirect. A huge error object overflows the session cookie.

The fix usually starts by asking a request-level question:

Is this message for the current response,
or for the response after the next request?

If it is for the current response, use flash.now.

If it is for the request after a redirect, use flash.

If it needs to survive multiple redirects, use flash.keep deliberately.

In a CookieStore app, flash bugs can also show up as response-size bugs. A controller that puts a long validation dump, serialized object, or exception message into flash[:alert] is not just creating a noisy UI message. It is increasing the session cookie payload that must be sent back to the browser. If a response suddenly starts failing after a large form error or imported-record validation report, inspect what was written to flash before treating it as a view problem.

Server-side session stores change the failure mode, not the rule. Redis or database-backed sessions can avoid cookie overflow, but they do not make object payloads safe. You still need to consider serialization, deployment compatibility, state snapshots, and cleanup.

Do not put records, exception objects, or validation objects in the flash. Store a short string, a small array of strings, or a compact code that the view can translate.

Flash makes one redirect feel continuous. It does not create a durable server state.

That distinction raises the next question.

Some state crosses one redirect and disappears. Some state, like a user ID, can persist across requests until logout. Rails can carry the identifier, but it still has to become a User object somewhere.

So, where does current_user actually come from?

You have a heavy controller action or a complex multi-step wizard. You need the Account object across multiple requests. Re-querying it on every request feels wasteful, so someone reaches for the closest thing that looks like request-to-request storage:

class AccountsController < ApplicationController
  def switch
    @account = current_user.accounts.find(params[:id])

    # Memoize this so we do not have to query it on the next request, right?
    session[:current_account] = @account

    redirect_to dashboard_path
  end
end

At the line where it is written, this looks harmless. session behaves like a hash. The assignment succeeds. The action redirects. Nothing about the controller tells you that you just asked Rails to serialize an Active Record object into an HTTP cookie.

In development, if the @account record is simple, it might even appear to work.

In production, as the application matures and that record accumulates loaded associations, it eventually blows up. The confusing part is that it doesn’t fail in your controller. It fails deep in the framework, long after your action has finished executing:

F, [2026-06-05T14:18:42.221934 #18412] FATAL -- :
[7f4f7d18-7c91-47c9-9cb9-01ec8d2b77c2]
ActionDispatch::Cookies::CookieOverflow (_billing_session cookie overflowed with size 6128 bytes):

[7f4f7d18-7c91-47c9-9cb9-01ec8d2b77c2]
actionpack (8.1.1) lib/action_dispatch/middleware/cookies.rb:616:in `check_for_overflow!'
actionpack (8.1.1) lib/action_dispatch/middleware/cookies.rb:698:in `commit'
actionpack (8.1.1) lib/action_dispatch/middleware/session/cookie_store.rb:117:in `set_cookie'
actionpack (8.1.1) lib/action_dispatch/middleware/session/abstract_store.rb:72:in `commit_session'

The stack trace points at commit_session, not AccountsController#switch.

That is the first important clue. The controller action has already finished. Rails is back in the middleware stack, trying to turn the response into bytes the browser can understand. Only then does the oversized session become a concrete failure.

This exposes a common broken assumption about state in Rails: the session is not a Ruby hash sitting in server memory. In a default Rails application, the session is backed by ActionDispatch::Session::CookieStore. When you write to it, you are not putting data into a process-local cache. You are asking Rails to serialize that data, encrypt it, authenticate it, and send it back to the browser as a cookie.

You did not save the object on the server. You packed it into a cookie and asked the browser to bring it back on the next request.

Where the Session Goes

By the time your controller action runs, Rails has already made the session available through the request context. That part feels ordinary:

session[:user_id] = user.id

After the action returns, the response travels back up the Rack middleware stack. ActionDispatch::Session::CookieStore gets a chance to persist the session.

CookieStore does not save the session to a database table or to Redis. It writes the session data into the cookie jar, using the configured session cookie key:

Rails.application.config.session_store :cookie_store, key: "_billing_session"

From there, the encrypted cookie jar takes over. For a modern Rails app using encrypted cookies, the flow looks like this:

session hash
  ->
serialized payload
  ->
encrypted and authenticated message
  ->
cookie value
  ->
Set-Cookie response header

Rails checks the final cookie name plus the encrypted value. If the result exceeds the cookie size limit, the response cannot be committed.

The controller line looked like a hash assignment. The system behavior was an HTTP write.

The Serialization Pipeline

Let’s trace how a Ruby hash becomes an HTTP header.

The CookieStore handoff is small, but important:

# action_dispatch/middleware/session/cookie_store.rb
def set_cookie(request, session_id, cookie)
  cookie_jar(request)[@key] = cookie
end

def cookie_jar(request)
  request.cookie_jar.signed_or_encrypted
end

That method writes the session value into the signed or encrypted cookie jar.

From there, the encrypted cookie jar does three things:

serialize the session
encrypt and authenticate the payload
check whether the final cookie is too large

The Rails source compresses that final step into a few lines:

# action_dispatch/middleware/cookies.rb
def commit(name, options)
  super
  options[:value] = @encryptor.encrypt_and_sign(
    options[:value],
    **cookie_metadata(name, options)
  )
  check_for_overflow!(name, options)
end

The important detail is not the exact encryption setup. It is the direction of travel:

session hash
  ->
serialized payload
  ->
encrypted cookie value
  ->
Set-Cookie header

New Rails applications use JSON serialization for cookies by default, though upgraded applications may still carry older serializer settings such as Marshall or hybrid modes. After serialization, Rails uses ActiveSupport::MessageEncryptor with keys derived from secret_key_base to seal the payload.

In a modern AES-GCM encrypted-cookie setup, the browser stores a value with this general shape:

sJqiplFlaBri/tctIKNc...--+TZCVdk0e/RzsuUf--W3J114mcEMz00DoeuAUNSw==

The pieces are the encrypted payload, the initialization vector, and the authentication tag.

If any part of that message is changed, Rails cannot decrypt and verify it. The session data is not accepted.

The exact cookie format can vary across Rails versions, cipher settings, metadata settings, and rotations. But the architecture is stable: CookieStore writes through the cookie jar, MessageEncryptor seals the payload, and the browser carries the sealed result back.

This pipeline also explains why the CookieOverflow appears after the controller action has finished. The oversized value is discovered when Rails tries to commit the encrypted cookie.

The session is encrypted and tamper-resistant, but the physical limits of HTTP headers still bind it.

The Four Kilobyte Ceiling

CookieStore is fast because it avoids server-side lookup of the session blob. It is also brutally small.

Browsers generally enforce a limit of around 4 KB (4096 bytes) per cookie. Rails checks the size of the cookie name plus the encrypted value before writing it. Encryption and metadata add overhead, so the useful payload is smaller than the raw browser limit.

That is why this mistake is so easy to misread:

session[:current_user] = @account

The same mistake often arrives through the flash:

redirect_to root_path, flash: { error: @account }

That looks like a temporary redirect message, but the flash is carried through the session. If the session is CookieStore, a large flash payload is still a large cookie payload.

You are not only storing the account’s ID. Depending on the serializer and object shape, you may be asking Rails to encode attributes, timestamps, loaded association data, dirty tracking state, or some other object representation that was never meant to cross the request boundary.

The failure mode is not always a clean overflow.

In a JSON-serialized app, a complex object often comes back as plain serialized data, not a live model:

session[:current_account] = @account

# Next request
session[:current_account].class
# => Hash

Now the bug depends on how the rest of the application uses that value. Code that only reads [“id”] might limp along. Code that expects an Account instance fails. Code that reads stale attributes may quietly make decisions from yesterday’s state.

In older Marshall or hybrid-serializer applications, the failure can be worse in another direction: the object-shaped value may round-trip more successfully, making it easier to believe that the session is storing application state safely. But that object is detached from the database. Its associations do not become fresh when a new request starts. Authorization, billing state, feature flags, account memberships, and plan limits can all change while the cookie still carries an outdated snapshot.

That is the trap.

The session can carry identity across requests. It should not carry the state that identity points to.

The Distributed Reality

Once you see the 4 KB limit, CookieStore can look oddly constrained. Why would Rails make this the default?

The answer lies in how a mature Rails application actually runs in production.

When you boot a Rails app locally with bin/rails server, you are often looking at a single process on a single machine. In that isolated environment, a global in-memory hash can appear to work. Production environments do not remain in that state for long.

A standard production config/puma.rb looks something like this:

# config/puma.rb
workers ENV.fetch("WEB_CONCURRENCY") { 4 }

threads_count = ENV.fetch("RAILS_MAX_THREADS") { 5 }
threads threads_count, threads_count

preload_app!

When this boots, Puma forks into four distinct worker processes. These are isolated operating system processes. Each process has its own Ruby heap. Threads inside a worker share memory, but workers do not.

Imagine you decided to build your own session store using a global Ruby hash. A user logs in, the load balancer routes their request to Worker 1, and you save GLOBAL_SESSIONS[session_id] = { user_id: user.id }.

When the next request lands, the load balancer might route it to Worker 3. That worker looks at its own isolated GLOBAL_SESSIONS hash, finds nothing, and boots the user back to the login screen.

From the user’s perspective, the application randomly forgot who they were.

You can try to patch this with sticky sessions at the load balancer, forcing a user to keep hitting the same backend. That only hides the coupling. It still gets awkward across deploys, worker restarts, autoscaling events, and multi-host routing.

Teams that need server-side revocation, larger session payloads, or compliance controls sometimes move session storage into Redis or a database-backed store. That changes the trade-offs: network calls, eviction behavior, cleanup, persistence, and capacity planning all become part of the session story. But it does not change the core lesson. Session should carry identity, not application state.

CookieStore chooses a different trade-off.

The browser carries the sealed session payload. Every Rails process that shares the same cookie configuration and secret_key_base can read it. Worker 1 does not need to remember what Worker 3 wrote.

The framework trades payload size for stateless web workers.

The Invalidation Problem

Once you accept that the session lives on the client, you run into the hardest problem of stateless architecture: invalidation.

Suppose a user’s account is compromised, or an administrator removes their access. You need to log them out immediately. Because the state is stored in a cookie, you cannot reach into every browser and delete it.

The naive approach is to add a database flag and check it on every request:

# The naive approach: Check this on every single request
class ApplicationController < ActionController::Base
  before_action :check_revoked_status

  def check_revoked_status
    if current_user.access_revoked?
      reset_session
      redirect_to login_path
    end
  end
end

This can be the right product behavior. It blocks the user as soon as the application sees the revoked state.

But it does not invalidate the cookie. The encrypted session still decrypts, and the browser still sends it. If someone copied that cookie earlier, they can replay the same encrypted string until the server rejects the state inside it. That is the replay attack shape this gate is defending against. The application had added a server-side check in front of the session, but it did not remotely destroy every copy of the cookie.

For global invalidation, the hard level is the secret material.

Encrypted session cookies are protected by keys derived from session_key_base. If you change that secret and do not accept the old one through cookie rotations, existing session cookies become unreadable across the fleet. That is effective during a serious security event, but it logs out everyone.

Cookie ratation needs precise language. Rails rotations are usually for migration: accept messages written with old keys while writing new ones with the new configuration. If the old key remains accepted, old sessions are not invalidated.

For a targeted invalidation, you need some server-side fact that can change.

The simple version is a user-level session token. Instead of treating user_id alone as enough, you store a random token in the session and compare it against the current token on the user:

class User < ApplicationRecord
  # Assume a `session_token` string column exists
end

# 1. During sign-in:
session[:user_token] = user.session_token

# 2. In ApplicationController:
def current_user
  @current_user ||= User.find_by(session_token: session[:user_token])
end

Now, when you need to log a user out of all devices forcibly, you rotate the token in the database:

def force_logout!(user)
  user.update!(session_token: SecureRandom.urlsafe_base64)
end

The next time that user makes a request, their browser sends the old token. User.find_by returns nil. They are logged out without changing anyone else’s session.

That model invalidates all devices for one user. If you need to revoke one device at a time, use a dedicated UserSession record and store a per-session token in the cookie. That rule is the same either way: CookieStore can carry the token, but the server-side record decides whether the token still means anything.

Store Identity, Not State

Rails goes out of its way to make the web feel stateful. session[:key] = value is one of the most elegant APIs in the framework, but its simplicity hides a distributed systems reality.

When you are deciding what to put in the session, use this rule of thumb: the session is a specialized transport mechanism, not a storage engine. Store identity, not state. Store IDs, not objects. The moment you try to use the client’s browser as a caching layer for your database, you are fighting the architecture of the framework itself.

Once the session contains only a user identifier, another question appears: where does current_user come from on the next request?

The action might call render.

It might call redirect_to.

It might call head.

Or it might do none of those things and still return a page.

The last case is classic Rails:

Class UsersController < ApplicationController
  def show
    @user = User.find(params[:id])
  end
end

There is no explicit render call here.

But if the request reaches UsersController#show, Rails can still render:

app/views/users/show.html.erb

People usually describe this as a convention. That is true, but it hides the lookup process underneath.

Rails is not looking at the URL and wandering through your app/views directory until something feels right.

By this point, Rails has already learned several facts from the request and the controller:

• which controller handled the request

• which action ran

• whether a response was already performed

• what format the request wants

• what variant is active, if any

• which template handlers are available

• which view paths the controller should search

The question for this article:

How does Rails decide which view template to render?

The Problem Rails Is Solving

Imagine if every controller action had to name its matching template:

class UsersController < ApplicationController
  def show
    @user = User.find(params[:id])

    render "users/show"
  end
end

Explicit rendering is sometimes exactly what you want. But most HTML controller actions follow a boring pattern:

run the action
prepare a few instance variables
render the matching template

If every ordinary action had to repeat that last line, Rails would make you spell out what the controller name and action name already imply.

The framework has enough information to treat this as the default:

UsersController#show
  ->
users/show

Because Rails supplies that default, this action can stay focused on application state:

def show
  @user = User.find(params[:id])
end

The action loads the data the view needs. Rails handles the conventional rendering step after the action finishes.

Rails does not implicitly render because the action was empty. It implicitly renders because the action finished without performing a response.

Implicit Rendering Is a Fallback

Rails keeps asking one request-level question: Has this request already chosen a response?

If the action calls redirect_to, the answer is yes.

If the action calls head :no_content, the answer is yes.

If the action calls render :profile, the answer is yes.

If the action finishes with none of those, the answer may be no. Now it's time for implicit rendering.

def show
  @user = User.find(params[:id])
end

After this method returns, Rails checks whether the response has already been performed. If not, ActionController::ImplicitRender tries to find a template for the current action.

For a full-stack Rails controller, the simplified decision looks like this:

did the action already render, redirect, or head?
  ->
yes: keep that response
no: try the default template for this action

Implicit rendering is not the same as rendering from inside the action.

This action renders explicitly:

def show
  @user = User.find(params[:id])

  render "profiles/show"
end

This action relies on the fallback:

def show
  @user = User.find(params[:id])
end

Both can produce HTML. But only the second one asks Rails to derive the template from the controller and action.

The Lookup Starts With a Name and a Prefix

For an ordinary controller action, the first two lookup facts are simple:

action name: show
controller path: users

Rails exposes that controller path directly:

UsersController.controller_path
# => "users"

Together, those point toward:

users/show

In filesystem terms, the usual template is:

app/views/users/show.html.erb

But internally, Rails does not only work with a complete filename. It works with a lookup request.

For a template render, Rails needs:

name
prefixes
partial or full template
details
view paths

In the simple UsersController#show case:

name: show
prefixes: users
partial: false
details: format, locale, variant, handler
view paths: app/views, plus any configured additions

Rails is not asking only whether app/views/users/show.html.erb exists.

It is asking closer to:

In the available view paths,
is there a full template named show,
under the users prefix,
matching the current request details?

Rails can then build a set of candidate templates instead of betting on one hard-coded filename.

A candidate template is a possible match for the logical template Rails wants to render. It is shaped by:

• the template name

• the prefixes

• the requested format

• the active variant

• the available handlers

• the view paths

Action View takes those facts and resolves the best-matching template.

The Filename Carries Request Details

A Rails view filename is compact metadata:

app/views/users/show.html.erb

It breaks down like this:

users       -> prefix
show        -> template name
html        -> format
erb         -> handler

The handler tells Action View how to process the template. In most Rails applications, that handler is ERB. Embedded Ruby inside an HTML template, evaluated into the response body.

Other handlers exist. Jbuilder, Builder, or another registered handler might back a template. But .html.erb is the default combination most Rails developers meet first:

html -> produce an HTML representation
erb  -> process the template with ERB

Notice that erb is not part of the template name. Rails is not specifically looking for a file called show.html.erb as one indivisible thing.

It is looking for a template named show under the correct prefix whose lookup details match the request.

Those details can include locale and variant, too:

app/views/users/show.en.html.erb
app/views/users/show.html+mobile.erb

The rough pattern is:

prefix/name.locale.format+variant.handler

Not every part has to be present. But each present part gives Action View more information to narrow the candidate list.

These files are separate candidates for the same logical template:

app/views/users/show.html.erb
app/views/users/show.json.jbuilder
app/views/users/show.html+mobile.erb

The filename tells Action View why each candidate is different.

Format Changes Which Template Rails Wants

The most common detail is format.

For a normal browser request, Rails is usually looking for HTML:

GET /users/1

The usual match is:

app/views/users/show.html.erb

But a request can ask for a different representation:

GET /users/1.json

Now Rails should not silently use the HTML template and pretend it produced JSON.

It should look for something that matches the requested format:

app/views/users/show.json.jbuilder

or another template capable of producing the requested response.

Missing-template errors often mention formats for this reason.

The problem is not always that there are no users/show templates.

Sometimes the problem is that a users/show template exists, but it’s not in the format this request asks for.

That matters most in controllers that serve more than one client:

def show
  @user = User.find(params[:id])

  respond_to do |format|
    format.html
    format.json
  end
end

The action name did not change.

The controller did not change.

The requested representation changed, so the template lookup changed.

Variants Narrow the Choice Further

Formats answer a broad question: “What kind of representation is this?”

Variants answer a narrower question: “What version of that representation should this request use?”

For example, a controller might set a mobile variant:

class ApplicationController < ActionController::Base
  before_action :set_variant

  private

  def set_variant
    request.variant = :mobile if mobile_browser?
  end
end

Now the same action can use a more specific template:

app/views/users/show.html+mobile.erb

If Rails is rendering users/show for an HTML request with the :mobile variant, it tries the mobile version before falling back to the generic HTML template.

The action is still:

def show
  @user = User.find(params[:id])
end

The lookup details are different. A request can change template lookup without changing the action body. Something earlier in the request may have changed the format or variant.

View Paths Decide Where Rails Searches

So far, we have talked about the logical template:

users/show

and the details:

html
mobile
erb

Rails also needs to know where to search.

Rails calls that list the controller’s view paths.

In a standard Rails app, the important path is app/views.

So the lookup users/show + html + erb can resolve to app/views/users/show.html.erb.

But view paths are not limited to one directory forever.

Engines, gems, controller-level overrides, and calls like prepend_view_path or append_view_path can change the places Rails searches.

A changed search path can explain why a template exists, but Rails does not use the one you expected.

The issue might not be the template name. It might be the search path.

Internally, ActionView::ViewPaths#lookup_context builds an ActionView#LookupContext from three ingredients:

view paths
details for lookup
prefixes

The lookup context gathers the facts Rails needs to find templates.

Template Inheritance Adds Fallback Prefixes

One Rails convention is easy to miss.

Rails can use controller inheritance when looking for templates and partials.

The Rails Guides give this example:

class AdminController < ApplicationController
end

class Admin::ProductsController < AdminController
  def index
  end
end

For Admin::ProductsController#index, Rails can look in this order:

app/views/admin/products/
app/views/admin/
app/views/application/

This makes app/views/application a useful place for shared partials.

The controller path gives Rails the most specific prefix first.

The inheritance chain can provide broader fallback prefixes after that.

Used deliberately, fallback prefixes give shared templates and partials a natural home. They also explain a strange class of bugs: “Why is Rails rendering a shared partial rather than failing?”

Sometimes it did not find the most specific template, but it did find a fallback template higher in the controller hierarchy.

Intentional fallback feels elegant. Accidental fallback sends you looking in the wrong file.

Layout Selection Is Related, But Separate

Finding the action template is not the whole story of rendering.

After Rails renders the template body, it often wraps that body in a layout:

app/views/layouts/application.html.erb

or a controller-specific or declared layout:

app/views/layouts/users.html.erb

Layout selection is a second decision layered on top of the template decision. The action template answers the question: “What content should this action produce?”

The layout answers the question: “What outer page frame should wrap that content?”

So this action:

def show
  @user = User.find(params[:id])
end

may involve both:

app/views/users/show.html.erb
app/views/layouts/application.html.erb

A rendering bug can live in either place.

Wrong page-specific content points to the action template or partials. Wrong navigation, scripts, title, or frame points to the layout.

What Happens When Rails Cannot Find the Template

Missing-template behavior is not only “file not found.”

When a normal controller action finishes without performing a response, ActionController::ImplicitRender tries the default template.

In Rails 8.1, the fallback sequence is roughly:

1. If the exact template exists, render it.

2. If the templates exist for other formats, variants, or handlers, raise UnknownFormat.

3. If this looks like an ordinary browser page load, raise MissingExactTemplate.

4. Otherwise, respond with 204 No Content.

A request that doesn’t render anything may not raise a missing-template error; Rails can decide that 204 No Content is the appropriate implicit response.

For API controllers, the implicit response is even simpler:

204 No Content

The same missing-template situation can therefore feel different depending on the request.

An HTML page load and a non-browser request do not carry the same expectation.

Rails is separating two cases:

It looks like you intended to render a page, but it's missing.

from:

This request may not need a body.

The debugging question should include the request format and request type, not only the controller action.

A Better Debugging Reflex

When Rails renders the wrong view, or fails to render the view you expected, do not start by starting only at the action body.

Ask what lookup Rails was trying to perform.

The practical sequence is:

Has this action already performed a response?
  render / redirect_to / head / before_action

If not, what action name is Rails using?
  show, index, new, edit, create, update, destroy

What prefix is Rails using?
  users, admin/users, or a fallback from controller inheritance

What format did the request negotiate?
  htmo, json, or something else

Is a variant active?
  mobile, tablet, or another custom variant

Which view paths are being searched?
  app/views, engine paths, prepended paths, configured additions

Is the issue in the action template or the layout?
  page body versus surrounding frame

The sequence turns “Rails cannot find my view” into a set of inspectable facts.

You can check the route.

You can check the controller path.

You can check the request.format.

You can check the request.variant.

You can check which view paths the controller is using.

View lookup has a concrete form: a query.

Rails takes the controller, action, request details, and view paths, then asks Action View for the best-matching template.

The familiar path app/views/users/show.html.erb is the result of that query in the simplest case.

Now the action finally gets its turn.

It can load records, check state, create something, enqueue work, assign instance variables, choose a format, or decide the user should be somewhere else entirely.

But after all that Ruby code runs, Rails still owes the outside world the same primitive output: an HTTP response.

HTTP doesn’t know about controller actions. It does not know about @user, current_user, service objects, partials, or Active Record.

At the boundary of the web server, the response has to become:

status
headers
body

Rack makes that contract explicit:

A request comes in. A response goes out. Rails exists partly to keep you from hand-building that tuple in every controller action.

The question for this article:

How does Rails turn controller execution into an HTTP response?

The Problem Rails Is Solving

Imagine if every Rails action had to return a Rack response directly:

class UsersController < ApplicationController
  def show
    user = User.find(params[:id])

    [
      200,
      { "Content-Type" => "text/html",
      ["<h1>#{user.name}</h2>"]
    ]
  end
end

That would be honest, but miserable. Every action would have to care about status codes, headers, content types, body construction, and response format. That is fine for a tiny Rack app, but not enough for a Rails controller.

Rails actions often need to do application work first:

def create
  @post = current_user.posts.new(post_params)

  if @post.save
    redirect_to @post
  else
    render :new, status: :unprocessable_entity
  end
end

This code is making a request-level decision:

If the post is saved, send the client somewhere else.
If it did not, show the form again with errors.

render, redirect_to, and head let the action talk in those terms instead of manually assembling [status, headers, body].

Why the Action’s Return Value Is Not Enough

A normal Ruby method is often understood by its return value:

def greeting
  "hello"
end

The method returns ”hello”. Controller actions do not work that way.

This action doesn’t send ”hello” to the browser:

class PagesController < ApplicationController
  def home
    "hello"
  end
end

Rails is not treating the final Ruby expression as the response body.

That feels odd until you consider the constraints under which Rails operates.

An action might render before the last line:

def preview
  render plain: "draft"

  Rails.logger.info("preview rendered")
end

An action might redirect from inside a branch:

def show
  unless current_user
    redirect_to login_path
    return
  end

  @profile = current_user.profile
end

An action might not call render at all:

def show
  @user = User.find(params[:id])
end

That last one is ordinary Rails. The action prepares data. Rails renders the default template afterward.

Rails does not ask: “What did the action return?”

It asks: “Has this controller performed a response yet?”

The difference is:

Ruby method return value
  ->
not the HTTP response

controller response state
  ->
render / redirect_to / head / implicit render
  ->
ActionDispatch::Response
  ->
[status, headers, body]

The Response Object Rails Is Building

By the time your controller action runs, Rails already has a response object for the request. Inside a controller, you can reach it with:

response

That object is an instance of ActionDispatch::Response.

It is where Rails stores the response state that will eventually become the HTTP response.

At the controller level, you usually do not manipulate that state directly:

 self.response_body = "<h1>Hello</h1>"

You usually write:

render :show

or

redirect_to users_path

or 

head :no_content

Inside the framework, ActionDispatch::Response is the actual object exposed through ActionController::Metal#response.

What render Changes

Start with explicit rendering:

Class UsersController < ApplicationController
  def show
    @user = User.find(params[:id])

    render :show
  end
end

At the level you write application code, this means: “render the show template.”

Rails then has to do several things:

• interpret the render arguments

• find the body content

• set response details such as content type and status

• assign the rendered body to the response

The controller-facing implementation anchor is:

ActionController::Rendering

Its render method checks whether a response body already exists and raises AbstractController::DoubleRenderError if you try to render again.

At the source level, the flow is: normalize the render options, call render_to_body, set content type information, and assign:

self.response_body = rendered_body

That assignment is why Rails considers the response to have been performed.

render doesn’t mean “send bytes to the browser right now.” It means: “put this rendered body into the response Rails is building.”

Once that body exists, Rails can say the response has been performed.

Rendering Is Not Only Templates

Template rendering is the common path:

render :show

which usually means Rails will look for something like:

app/views/users/show.html.erb

But render is broader than HTML templates.

You can render plain text:

render plain: "ok"

You can render JSON:

render json: { id: @user.id, name: @user.name }

You can render with a non-200 status:

render json: { error: "Not found" }, status: :not_found

Different renderer, same job: “choose the response body and response metadata.”

Template rendering eventually flows into Action View: template lookup, layouts, formats, variants, and rendering handlers.

That subsystem deserves its own deep dive. For now, the important point is narrower: render is one way a controller action performs the response.

When Rails Renders For You

Now take the explicit render away:

class UsersController < ApplicationController
  def show
    @user = User.find(params[:id])
  end
end

That is not an empty response. In a regular HTML controller, Rails can use the action name and controller name to look for a default template:

app/views/users/show.html.erb

The action prepares the state:

@user = User.find(params[:id])

Action View can then render the template that corresponds to the action.

Rails actions can look smaller than the work they trigger. The last visible line in the action is not the last thing Rails does for the request.

ActionController::ImplicitRender handles actions that finish without explicitly calling render, respond_to, redirect_to, or head.

In a regular controller, Rails may render the matching template. In an ActionController::API controller, templates are not part of the default stack; Rails expects you to call render or redirect_to for real content, and otherwise returns 204 No Content.

If your action did not explicitly perform a response, Rails may still perform one after the action finishes.

Redirects Are Responses Too

A redirect is not a render.

def create
  @user = User.create!(user_params)
  
  redirect_to @user
end

This does not render the user’s show page inside the same request.

It sends the client a response that says: “Go to this other URL next.”

At the HTTP level, that response is roughly:

status: 302
Location: /users/42
body: ""

Then the browser makes a second request:

GET /users/42

That second request may render the show page.

The source-level path of redirect_to reveals the same response-state idea:

self.location      = ...
self.response_body = ""
self.status        =

So redirect_to performs a response by setting a Location header, an empty body, and a redirect status.

It tells the client where to go.

redirect_to Does Not Stop Ruby

redirect_to performs a response, but it does not stop the current method.

This action is buggy:

def create
  unless current_user
    redirect_to login_path
  end

  @post = current_user.posts.create!(post_params)

  redirect_to @post
end

When current_user is nil, it raises the very ordinary Rails pain:

NoMethodError: undefined method `posts` nil

Or, if later code runs, the method may attempt a second response.

Use Ruby control flow when you want the method to stop:

def create
  unless current_user
    redirect_to login_path
    return
  end

  @post = current_user.posts.create!(post_params)

  redirect_to @post
end

The rule:

redirect_to changes the response
return changes the Ruby execution

Rails tracks the response. Ruby still runs your method.

head Builds the Minimal Response

Sometimes the response does not need a body.

def destroy
  @post.destroy!

  head :no_content
end

That sends a 204 No Content response.

No template. No JSON. No HTML.

Just the response status and headers.

head is useful when the response itself is the signal:

head :forbidden
head :no_content

ActionController::Head sets the status, applies headers such as Location when provided, and assigns an empty response body.

So the controller response options line up like this:

render       -> response with a body
redirect_to  -> redirect response with a Location
head         -> response with status and headers

Different helpers, same goal: build the HTTP response Rails will return.

Why Rails Raises Double Render Errors

Once Rails has a response body, it has to protect that decision.

This action tries to perform two responses:

def show
  @user = User.find(params[:id])

  render :show
  render plain: "done"
end

The first render assigns a response body.

The second render attempts to assign a different body to the same request.

Rails raises: AbstractController::DoubleRenderError

The same mistake can happen with redirects:

def create
  @post = Post.create!(post_params)

  redirect_to @post
  render :new
end

Both lines are trying to perform the response.

Rails exposes this state through

performed?

In ActionController::Metal, the check is compact:

response_body || response.committed?

Most controller actions hit the first side of that check: render, redirect_to, or head, which assign a response body. response.committed? covers lower-level cases where the response has already been committed, such as streaming, and Rails should no longer treat the action as free to choose another response.

That check is why branch structure matters:

def create
  @post = Post.new(post_params)

  if @post.save
    redirect_to @post
  else
    render :new, status: :unprocessable_entity
  end
end

Only one branch performs the response. No accidental fall through. No second render hiding below the first.

The Response Still Leaves Through Rack

After the controller performs a response, Rails still has to return to the Rack contract:

[status, headers, body]

ActionDispatch::Response#to_a prepares the response and returns the Rack-compatible status, headers, and body.

Then the response travels back outward through the middleware.

That means your controller may not be the last code to touch it.

Middleware can still:

• write cookies

• add security headers

• adjust cache headers

• handle HEAD requests

• log response details

• turn exceptions into error responses

The controller performs the application response. Rack and middleware carry it back to the server, and the server sends it to the client.

A Better Debugging Question

When response behavior looks wrong, do not start with:

What did this action return?

Start with:

Where was the response performed?

That question leads you through the right path:

Did a before_action render, redirect, or call head?
  ->
Did the action explicitly perform a response?
  ->
Did execution continue after redirect_to?
  ->
Did Rails fall through to implicit rendering?
  ->
Did two branches try to perform responses?
  ->
Did middleware change the response afterward?

If Rails is looking for a template you did not expect, check implicit rendering.

If a redirect occurred but the later code still ran, add Ruby control flow.

If you see DoubleRenderError, find the two response-performing paths.

If headers appear from nowhere, keep walking outward into middleware.

The action matters, but it is one step in Rails’ response-building path, not a little function whose return value becomes HTTP.

The Core Principle

Rails lets controller actions stay focused on request decisions:

render :show
redirect_to @post
head :no_content

Under those helpers, Rails is still doing the old web job: “turn this request into status, headers, and body”.

The full path is:

route matched
  ->
params assembled
  ->
callbacks run
  ->
action executes
  ->
render / redirect_to / head / implicit render
  ->
ActionDispatch::Response
  ->
Rack response
  ->
middleware
  ->
Client

Rails actions do not return HTTP responses. They perform a response state that Rails turns into status, headers, and body.

Now the action has the request data.

But data is not the only thing an action needs.

Before a controller action can safely do its work, a Rails app often has to answer a few other questions:

• Who is making this request?

• Which account, tenant, project, or record does this request belong to?

• Is this user allowed to continue?

• Should this request be redirected before the action runs?

• Is there a shared request context that the action should be able to assume?

Those questions rarely belong to a single action. They sit at the edge of many actions.

For example, a reporting action may look like this:

class ReportsController < ApplicationController
  def index
    @reports = current_account.reports.visible_to(current_user)
  end
end

That action reads cleanly, but only because it assumes some things are already true:

• there is a signed-in user

• there is a current account

• the current user is allowed to see reports for that account

If those things are not true, the action should probably not run at all.

before_action exists because controller actions usually need a place for request prerequisites.

The question for this article:

Why does Rails have a mechanism for running code before the controller action?

Every Action Has a Hidden Prologue

Imagine writing every controller action with all its prerequisites inline:

class ReportsController < ApplicationController
  def index
    redirect_to login_path and return unless current_user

    @account = current_user.accounts.find(params[:account_id])

    unless current_user.can_view_reports?(@account)
      head :forbidden and return
    end

    @reports = @account.reports.visible_to(current_user)
  end
end

As a single method, this is readable. You can go top to bottom and see the whole path.

The trouble starts when the same checks show up in show, new, create, update, destroy, and every custom action that belongs to the same part of the app.

So the controller starts to develop a repeated pattern:

make sure there is a user
find the current account
check access
load a record
then do the action-specific work

Repetition is only part of the problem. The action-specific work is also mixed in with request setup.

The action is supposed to answer a narrow question: “What should happen for this request?”

Before it can answer that, the application must establish the conditions under which the action may proceed.

Preconditions Before Action-Specific Work

before_action is Rails’ way of expressing controller preconditions.

It gives the controller a place to say: "Before this action runs, these conditions must be met or already prepared”.

So instead of repeating the same setup inside every action, you can write:

class ReportsController < ApplicationController
  before_action :authenticate_user!
  before_action :set_account
  before_action :authorize_reports!

  def index
    @reports = @account.reports.visible_to(current_user)
  end
end

Now the action has a cleaner job. Authentication, account lookup, and request-boundary checks no longer crowd the method body.

It can assume the prerequisites declared above it.

The flow is:

request enters controller
  ->
preconditions and setup run
  ->
action-specific code runs

before_action fits naturally into Rails controllers because controllers already operate around shared request setup.

They are not collections of unrelated Ruby methods. They are request handlers.

before_action is one way Rails lets you name those boundaries.

What Belongs Before an Action

Good before_action callbacks usually do one of three things.

They can protect the request:

before_action :authenticate_user!
before_action :require_admin!

They can establish a request context:

before_action :set_locale
before_action :set_current_account

They can load the state that several actions need:

before_action :load_project
before_action :load_invoice, only: [:show, :edit, :update]

In each case, the callback answers a question that the action should not have to keep asking from scratch.

By the time this action runs:

def show
  @line_items = @invoice.line_items.order(:created_at)
end

the controller has already established:

there is a current user
there is a current account
there is an invoice
the current user can reach it

The promise is useful, and it is where callbacks can sometimes become dangerous.

The action looks small because some of the actual execution has moved elsewhere.

When the moved code is genuinely prerequisite work, the action gets cleaner. When the callback is doing the action’s real job in disguise, the controller gets harder to read.

A good practical rule:

Use before_action for things the action should be able to assume, not for things the action is supposed to decide.

That is more a readability rule than a Rails rule, but it explains why some callbacks make a controller cleaner while others make the actual behavior harder to find.

Why Callback Helpers Are Usually Private

One small Rails detail hides in most controller examples.

Callback methods are usually placed under private:

class ReportsController < ApplicationController
  before_action :authenticate_user!

  def index
    @reports = Report.visible_to(current_user)
  end

  private

  def authenticate_user!
    redirect_to login_path unless current_user
  end
end

The placement is intentional.

Rails treats public controller methods as possible actions. Internally, AbstractController::Base.action_methods builds the set of action names from public instance methods, after removing Rails’ own internal methods.

The visibility tells Rails and future readers which methods are endpoints and which are supporting code.

Since before_action sites near the top of the controller, right next to the action-facing surface, marking callback helpers private keeps the distinction clear:

public methods are actions
private methods support execution

Not every controller method is meant to be reachable as an endpoint.

How Rails Turns That Idea Into Execution

When you write:

before_action :authenticate_user!

Rails is not inserting a method call at the top of your action method. It is registering a callback around action processing.

The controller callback machinery lives in Action Pack, primarily through:

AbstractController::Callbacks

That module uses Rails’ general callback system:

ActiveSupport::Callbacks

The internal shape is small:

def process_action(...)
  run_callbacks(:process_action) do
    super
  end
end

Rails has a process_action step to execute controller actions, and callbacks are registered around it.

Conceptually, this:

before_action :authenticate_user!

adds a before callback to the :process_action callback chain.

The source-shaped version is roughly:

set_callback(:process_action, :before, :authenticate_user!)

The declaration at the top of the controller is not metadata. It becomes executable control flow around the action.

It is part of the framework path that leads to your action. The public API for this behavior is documented in AbstractController::Callbacks, AbstractController::Callbacks::ClassMethods, and ActiveSupport::Callbacks.

A Callback Can Decide the Action Should Not Run

When a precondition fails, before_action becomes more than setup: it can stop the action from running.

The most common example is authentication:

class ReportsController < ApplicationController
  before_action :authenticate_user!

  def index
    @reports = Report.visible_to(current_user)
  end

  private

  def authenticate_user!
    redirect_to login_path unless current_user
  end
end

For a signed-in user, the flow is:

authenticate user
  ->
index

For a guest, the flow is:

authenticate user
  ->
redirect to login
  ->
index does not run

If the request is not allowed to reach the action, the callback should be able to choose a response before the action-specific code runs.

In controller callbacks, rendering, redirecting, or calling head marks the response as already performed. Rails uses that to halt the normal path before the action runs.

The internal callback setup is built around that idea. The source-level shape checks whether the controller has already performed a response:

controller.performed?

You may also see callbacks being halted with:

throw(:abort)

That belongs to the broader Rails callback vocabulary, especially around model callbacks. For controller before_action debugging, the everyday path is usually more concrete: a callback rendered, redirected, or called head, so the controller has already performed a response.

That leads to a common debugging question:

Why is my action not running?

The answer is not always routing.

It may be:

A before callback has already performed the response.

redirect_to Does Not Stop the Current Method

One small Ruby detail sits inside that controller behavior.

redirect_to can prevent the action from running, but it does not automatically stop Ruby from executing the rest of the current callback method.

The subtle bug appears here:

def authenticate_user!
  redirect_to login_path unless current_user

  AuditLoginAttempt.create!(user_agent: request.user_agent)
end

If current_user is missing, Rails will mark a redirect response as performed.

But Ruby can still continue to the next line inside authenticate_user!.

So if you want the callback method itself to stop, say so:

def authenticate_user!
  return if current_user

  redirect_to login_path
end

or:

def authenticate_user!
  redirect_to login_path and return unless current_user
end

The distinction:

redirect_to affects the controller response
return affects the Ruby method

Rails uses the performed response to decide whether the action should continue. Ruby still uses ordinary method control flow inside the callback.

Order Matters Because Preconditions Depend on Each Other

Once you think of before_action as prerequisites, order becomes easier to reason about. Some prerequisites depend on earlier prerequisites.

This order makes sense:

class ProjectsController < ApplicationController
  before_action :authenticate_user!
  before_action :set_account
  before_action :load_project

  def show
  end

  private

  def set_account
    @account = current_user.accounts.find(params[:account_id])
  end

  def load_project
    @project = @account.projects.find(params[:id])
  end
end

The chain has a dependency:

authenticate_user!
  ->
set_account
  ->
load_project
  ->
show

set_account assumes current_user.

load_project assumes @account.

The action assumes @project.

If you reverse the first two callbacks, the controller may try to find an account through a missing user. If you load the project before the account, the lookup has the wrong boundary.

In complex apps, the chain often grows gradually. One callback is added for authentication. Another for tenancy. Another for a feature flag. Another for authorization. Eventually, the order is not just a list. It is a small execution graph written as a list.

When this list changes, behavior changes.

A Quick Word About around_action

Most controller callback discussions start with before_action, because it is the one you see most often.

Rails also has after_action, which runs action processing, and around_action, which wraps action processing.

For example:

around_action :measure_runtime

An around_action is useful when the callback needs to surround the work rather than simply run before it.

The flow is close to:

around_action begins
  ->
action processing yields
  ->
around_action finishes

The exact order can depend on how the callbacks are declared, which is a deeper topic, perhaps for another time. For now, it is enough to see that these callbacks belong to the same controller execution story. Rails runs an action-processing chain, not just calls a method named after the action.

The Chain May Be Longer Than the Controller File

One reason callbacks surprise people is that the visible controller file may not contain the whole chain.

Most Rails apps put broad request prerequisites in ApplicationController:

class ApplicationController < ActionController::Base
  before_action :set_locale
  before_action :authenticate_user!
end

Then a specific controller adds its own prerequisites:

class Admin::ReportsController < ApplicationController
  before_action :require_admin!
  before_action :load_report

  def show
  end
end

The local file shows:

require_admin!
load_report
show

But the request may actually pass through:

set_locale
authenticate_user!
require_admin!
load_report
show

Inheritance keeps broad request boundaries out of every individual controller. It also means an action can be affected by code that lives above it.

So, when debugging callbacks, do not read only the action’s file.

Read the controller ancestry:

• ApplicationController

• namespace base controllers like Admin::BaseController

• included controller concerns

• authentication or authorization modules

• any skip_before_action or prepend_before_action

The action may be local, but the chain is often inherited.

When a Controller Needs an Exception

Inherited callbacks are useful until one controller needs a different boundary.

Suppose ApplicationController requires authentication:

class ApplicationController < ActionController::Base
  before_action :authenticate_user!
end

Most controllers should inherit that.

But a public marketing page may need to skip it:

class PagesController < ApplicationController
  skip_before_action :authenticate_user!, only: [:home]

  def home
  end
end

That is what skip_before_action is for. It removes a callback from the chain for the actions you specify.

It doesn’t pass authentication. It changes the callback chain so the authentication callback doesn’t run for that action.

Rails also gives you prepend_before_action when a callback must run before callbacks that were already registered.

prepend_before_action :set_current_tenant

Use that sparingly, however. If callback order is already hard to see, prepending can make the chain even less local. But when a prerequisite must happen first, it is part of the callback toolbox.

Conditions Make Preconditions Selective

Not every action needs the same prerequisites.

Rails lets you write:

before_action :load_invoice, only: [:show, :edit, :update]

or:

before_action :authenticate_user!, except: [:index, :show]

Conceptually:

only: :show

means:

if: ->(controller) { controller.action_name == "show" }

So a callback can be present in the controller and still not apply to the action you are debugging.

There are two different failure modes:

• the callback was not in the chain

• the callback was in the chain, but its conditions did not match

Rails may have skipped it correctly.

A Practical Debugging Path

Suppose this request keeps redirecting to login:

GET /reports

You expected:

ReportsController#index

to run, but your log line inside the action never appears.

The action may not have been the first application method Rails tried to run. Something earlier in the chain may have answered the request first.

Instead of asking only why Rails did not call the action, ask:

What happened before the action?

Walk the request in this order:

Did the route match the controller and action I expected?
  ->
Which before_action callbacks apply?
  ->
Are any inherited from ApplicationController or a parent controller?
  ->
Did one render, redirect, or call head?
  ->
Did the callback order cause an earlier failure?

If you need to inspect the assembled callback chain, Rails exposes it:

ReportsController._process_action_callbacks.map do |callback|
  [callback.kind, callback.filter]
end

Do not build application behavior on that. Use it as a debugging aid.

It can show you what Rails has registered around process_action, including callbacks inherited from parent controllers.

The Trade-Off

before_action gives Rails controllers a clean way to express shared request prerequisites.

The cost is locality. The action body no longer tells the whole story.

There are request prerequisites:

before_action :authenticate_user!
before_action :set_current_account
before_action :load_project

These start hiding behavior:

before_action :calculate_dashboard_metrics
before_action :choose_pricing_experiment
before_action :maybe_create_trial_subscription

Now the callback list is doing more than preparing the request; it is hiding behavior the action probably ought to make visible.

The question is not:

Should I use callbacks or avoid them?

Instead, ask:

Is this code a prerequisite for the action, or is it the action’s real work?

If it is a prerequisite, before_action may be a good fit.

If it is the real work, hiding it in a callback makes the controller harder to read.

What to Remember

before_action exists because Rails actions often need shared preconditions.

The action should be able to say:

def show
  @comments = @project.comments.recent
end

without repeating every step required to make @project safe and meaningful.

Rails gives controllers a pre-action layer:

route matched
  ->
params assembled
  ->
controller instance prepared
  ->
before_action prerequisites
  ->
action-specific code
  ->
response

Internally, that layer is grounded in AbstractController::Callbacks, using ActiveSupport::Callbacks, around the process_action method.

Once you see callbacks as request preconditions, the trade-offs become easier to evaluate: cleaner action bodies, less local control flow, and a chain you now know how to inspect.

params is assembled before your action runs.

We use params so often that it can feel like it simply shows up in the controller, ready to use.

But params is not just one thing.

It is a mashup, pieced together from different parts of the request.

This is worth understanding because many controller bugs come down to the shape of the params. Maybe a value is missing, or a nested key is not where you thought it would be. Sometimes JSON does not get parsed. Sometimes an id shows up from an unexpected place. Other times, Strong Parameters quietly filters something out, making it seem like Rails never received it in the first place.

To debug these kinds of problems, it helps to have a clearer picture of where the params come from.

By the end of this article, you should be able to answer this question clearly:

How does Rails build the params object your controller action reads?

Let’s Get the Right Mental Picture

params is a merged request structure built from route, query, and request body params.

When your controller action runs, you get to reach for a single object:

params

But behind the scenes, Rails pieced that object together from several places:

Route params
Query params
Body params
  ->
controller params

So when you write:

def show
  User.find(params[:id])
end

That line looks like ordinary Ruby.

But params[:id] is already the result of work Rails did earlier: matching the route, parsing the request, and preparing a controller-facing structure before the action began.

The Three Sources of params

For most controller actions, the useful way to read params is to separate them back into their sources.

Take this request:

PATCH /users/42?tab=settings

with a form body like:

user[name]=Syed

By the time this request reaches a controller action, Rails may expose all of those values through params. But each piece entered the request through a different door.

Route Params Come From the Matched Route

Route params are born in the router.

Suppose your routes include:

patch "/users/:id", to: "users#update"

and the request is:

PATCH /users/42

The router matches the path pattern and extracts the dynamic segment:

{ id: "42" }

That value came from the path itself.

As we saw while understanding how routing worked, dynamic segments become route params. The controller action doesn’t inspect the URL path and pull out "42" manually. The router already did that work before the dispatch reached the action.

So when UsersController#update reads:

params[:id]

It is usually reading a value that the router extracted from the path.

This shows up quickly when params[:id] is missing. The first question shouldn’t be “what did my action do wrong?” The first question should be:

Did the route that matched this request actually define an :id segment?

Query Params Come From the URL After ?

Query params come from the query string, the part of the URL after the question mark.

For a request like:

PATCH /users/42?tab=settings

Rails can parse:

tab=settings

Query params are common for filters, search terms, pagination, and view state:

GET /users?page=2&sort=name

Those values are not route params, nor body params. They are request data encoded in the URL itself. But once Rails assembles controller params, you usually access them the same way:

params[:page]
params[:sort]

That is convenient, but it can hide the source of a value. params[:tab] doesn’t tell you where tab came from. It only tells you that the tab is present in the merged structure.

Body Params Come From Submitted Request Data

Request body params come from data submitted in the request body. For a normal HTML form submission, the browser sends fields using names like:

user[name]=Aslam

For a JSON API request, the client might send:

{
  "user": {
    "name": "Aslam"
  }
}

In controller code, though, Rails still presents them through params:

params[:user]

That means a single request can contribute to params from multiple places at once.

For example:

PATCH /users/42?tab=settings

with:

user[name]=Aslam

can give the controller a merged params share like:

{
  "id" => "42",
  "tab" => "settings",
  "user" => {
    "name" => "Aslam"
  }
}

At the controller boundary, all of that data shows up through one object, but it didn’t enter the request as one thing.

How Rails Merges Them

Once Rails has these pieces, it has to combine them into one structure. The precedence looks like this:

body params < query params < route/path params

Rails starts with request body params, overlays query params, and then overlays route params.

The source-level shape is roughly:

request_parameters.merge(query_parameters).merge!(path_parameters)

• request_parameters are body params.

• query_parameters are query string params.

• path_parameters are the route params.

Because later params win, route params take precedence when the same top-level key appears in multiple sources.

So if you have a route like:

patch "/users/:id", to: "users#update"

and a request like:

PATCH /users/42/id=99

The path still says:

id = "42"

The query string also says:

id = "99"

But in the final merged params, the route value wins:

params[:id] # 42

If a top-level param value seems to come from the “wrong” place, remember that params is merged. The final object doesn’t show you the source history. It only shows you the winning value.

How Nested Params Get Their Shape

One of the most common surprises with params is that it can contain nested hashes and arrays. That shape often starts with bracket notation.

For example, an HTML form might submit fields named:

user[name]=Aslam
user[email]=aslam@example.com

Rails parses those names into a nested structure:

{
  "user" => {
    "name" => "Aslam",
    "email" => "Aslam@example.com"
  }
}

So the controller code can say:

params[:user][:name]

The nested hash is not something Rails guessed. It came from the way the submitted fields were named. The same idea applies to deeper nesting:

user[address][city]=Bangalore

which becomes conceptually:

{
  "user" => {
    "address" => {
      "city" => "Bangalore"
    }
  }
}

Arrays use bracket notation too:

ids[]=1&ids[]=2

There are plenty of deeper parser details here, especially around arrays of hashes and invalid shapes. But the rule is enough for most controller debugging:

Nested params usually come from nested parameter names.

If the submitted name is:

name=Aslam

Then you shouldn’t expect:

params[:user][:name]

to exist.

The shape of params follows the shape of the submitted keys.

How JSON Body Params Join the Same Structure

JSON follows the same broad idea: data in the request body can be included in the params. The difference is the format Rails has to parse.

Suppose the client sends:

{
  "user": {
    "name": "Syed"
  }
}

with a content type like:

Content-Type: application/json

Rails can parse that JSON body and make it available through params:

params[:user][:name] # Syed

From inside the controller, it can look almost the same as a form submission.

For form-encoded data, Rails is parsing bracket-style parameter names. For JSON, Rails is parsing a JSON document.

Either way, the result becomes request body params. Then those body paras are merged into the same final params object as the route and query params.

If a client sends something that looks like JSON but doesn’t identify it as JSON, Rails may not parse it the way you expect. API debugging often starts with boring-looking details:

• What body did the client send?

• What Content-Type header did it send?

• Did Rails parse the body into request.request_parameters?

There is one small Rails behavior worth keeping in mind here.

If the JSON body is not an object at the root, Rails wraps it under _json.

The default JSON parameter parser decodes the body and returns the decoded hash directly. But if the decoded value is not a hash, Rails returns:

{ _json: data }

So a body like:

["a", "b"]

is not merged as a top-level key. Rails needs a key to attach it to, so it becomes available under _json.

That is not usually the main path in standard Rails controllers, but it is useful when debugging API requests. The behavior is visible in the DEFAULT_PARSERS definition in the ActionDispatch::Http::Parameters API docs.

Strong Parameters Come Later

Strong Parameters are related to params, but they happen at a different step.

params is built first, and the Strong Parameters step decides later which parts are allowed for mass assignment.

For example:

def user_params
  params.require(:user).permit(:name)
end

This code doesn’t create the incoming user params. It filters the params structure that Rails already built.

Suppose the email parameter was expected and didn’t make it through. That doesn’t mean Rails failed to receive email. Rails might’ve received it, built it into prams, and then Strong Parameters filtered it out because :email was not permitted.

So when debugging, separate the two questions:

• Did Rails receive and parse the param?

• Did Strong Parameters permit it?

Those are different problems: one is about request parsing and merging; the other is about controller-level filtering.

Debugging When params Look Wrong

When params don’t look right, it’s easy to focus on the controller action. But often, the issue starts earlier in the request process.

Here are some helpful questions to ask:

Is the Missing Param Actually in the Route?

If params[:id] is missing, start with the route. A route like:

get "/users", to: "users#show"

doesn’t define an :id segment.

So this request:

GET /users?id=42

may still give you an id, but that value came from the query string, not the route.

With you have defined a route like the following, the id comes from the path:

get "/users/:id", to: "users#show"

When in doubt, inspect the route set:

bin/rails routes

The route pattern tells you which path parameter can exist.

Did a Collision Hide the Value You Expected?

If the same key appears in more than one source, the final params object only shows one value.

For example:

PATCH /users/42?id=99

You might expect the query string value to take precedence because it appears at the end of the URL. But Rails merges route params last, so:

params[:id] # "42"

If a value looks surprising, compare the sources instead of only looking at the merged result:

request.path_parameters
request.query_parameters
request.request_parameters

Those three methods show you the pieces before they become the final controller-facing params. Often, comparing those three sources is the fastest way to find where the confusion entered.

Did the Submitted Shape Match the Code?

Nested params depend on submitted key names. If your controller expects:

params[:user][:name]

then the submitted form field needs a nested name like:

user[name]

If the field was submitted just as name, then the shape is different: params[:name].

The issue isn’t with the params themselves; it’s a mismatch between the structure of the submitted data and what the controller expects.

This happens often in custom forms, API clients, JavaScript submissions, and tests that build params by hand.

Did Rails Parse the Body?

If the body params are missing, check whether Rails parsed the body at all. For JSON requests, the first place to look is the content type.

A client might send a body that looks like JSON:

{
  "user": {
    "name": "Syed"
  }
}

But if the request doesn’t identify it as JSON, Rails may not put it into params the way your controller expects. So this header matters:

Content-Type: application/json

Again, the useful debugging move is to separate the sources:

request.request_parameters

If the body params are missing, the issue is earlier than Strong Parameters and before the action logic.

Is This Really a Symbol or a String?

Inside controllers, params is usually forgiving about symbol and string access:

params[:user]
params["user"]

Both work in normal controller code.

Rails wraps params in ActionController::Parameters, which supports indifferent access for this kind of lookup. But the confusion can appear after you convert or pass data around:

params[:user].to_h

Or, when a plain Ruby hash enters the picture in tests or service objects.

Controller params are forgiving. Plain hashes may not be.

So if symbol and string access behave differently, ask whether you are still working with ActionController::Parameters or whether the data has been converted into an ordinary hash.

What to Remember

params is not a single object that simply appears inside your action. It is the result of parsing and merging request data.

The shape looks like this:

request body params
  + 
query string params
  + 
route/path params
  ->
params before your action runs

And the precedence is:

body params < query params < route/path params

That means:

• body data supplies submitted form or JSON values

• query data supplies values from the URL after ?

• route data supplies values extracted from the matched path

• route params win when top-level keys collide

• Strong Parameters filter the structure after it has already been built

The controller action in not where request data begins. It reads a request structure that Rails has already assembled.

And once the action has read that request structure, Rails still has another job ahead: turning the action’s result into an HTTP response.

But that decision is only the handoff.

Once a route is chosen, Rails still has to turn that decision into an actual method call on a controller. It has to resolve the controller, build a fresh controller instance, assemble the request state, run callbacks, and only then execute the action.

That step is called dispatch.

From the outside, this part of Rails feels deceptively simple:

route matches ⭢ action runs

Internally, there is more structure than that.

By the end, you should be able to answer this question clearly:

What actually happens between the router choosing a route and my controller action running?

Start With the Right Mental Model

Controller dispatch is the process of turning a matched route into a controller action execution.

The router decides where the request should go. Dispatch decides how that decision becomes live application code.

The flow looks like this:

Route match
  ⭢
Controller class identified
  ⭢
Controller instance created
  ⭢
Request context and params assigned
  ⭢
Callbacks run
  ⭢
Action invoked
  ⭢
Response returned

That flow explains most controller-level confusion:

The router decides where the request goes.

Dispatch decides how it gets executed.

What the Router Actually Hands Off

By the time dispatch begins, the router has already done its job.

For a route like:

get "/users/:id", to: "users#show"

and a request like:

GET /users/42

Rails has already identified the basic routing outcome:

• controller name: "users"

• action name: "show"

• route params: { id: "42" }

At this point, Rails has still not run controller code. It has only identified what should run.

Route recognition gives Rails a target. Dispatch turns that target into execution.

Routing Produces Identifiers. Dispatch Turns Them into Objects

The route target usually appears in Rails code as something like:

"users#show"

That is not yet a controller instance. It is a pair of identifiers:

• controller path: "users"

• action name: "show"

During dispatch, Rails resolves that controller path into the actual controller class:

"users" ⭢ UsersController

For a namespaced controller, the same pattern applies:

"admin/reports" ⭢ Admin::ReportsController

The routing layer and controller layer are separate parts of the framework. The route set identifies the target in a form Rails can carry forward, and then the controller dispatch layer resolves that target into the controller class that will actually handle the request.

There is no need to memorize the internal classes involved for this distinction to be useful.

Routing produces identifiers. Dispatch turns them into objects.

Each Request Gets a Fresh Controller Instance

Once Rails knows which controller class should handle the request, it creates a new instance of that controller for the request.

That means if the request is headed to:

UsersController#show

Rails doesn’t reuse some long-lived controller object sitting around in memory waiting for work. It instantiates a fresh controller object for this request.

• controller instance variables are request-scoped

• one request does not share the controller instance state with another

• controller objects are part of per-request execution, not long-lived application state

Each request gets a fresh controller instance.

The object exists for one request-shaped unit of work.

Before the Action Runs, Rails Builds the Request Context

Once the controller instance exists, Rails still is not ready to run your action method.

It first has to attach the request context that controller code expects to exist.

• request

• response

• params

• session

• cookies

become available through the controller layer.

That doesn’t mean all of that state is born in the controller itself. Much of it was prepared earlier by middleware or routing. But by the time dispatch sets up the controller execution context, Rails has gathered that state into the shape the controller code knows how to use.

By the time your action starts, a lot of the system work has already happened.

How Params Are Built Before Your Action Starts

One of the most important pieces of that request context is params.

We use params constantly, but it is easy to treat them as if they just appear fully formed inside the action. They do not.

params is assembled before your action runs.

Conceptually, Rails is combining multiple sources of request data:

• route params

• query params

• request body params

So if you have a route like:

get "/users/:id", to: "users#show"

and a request like:

GET /users/42?tab=profile

then by the time the action runs, the controller can see values that came from different places:

• route param: id = “42”

• query param: tab = “profile”

Similarly, for a form submission or JSON request, body data joins the picture too.

The exact internal mechanics of parameter parsing deserve their own article1, so this piece should not overload that part of the system. But the distinction belongs here:

params is not created by your action. It is assembled before your action begins.

It also explains one common class of confusion: when params look wrong, the cause is often earlier than the action itself.

Your Action Does Not Run in Isolation

At this point, Rails has:

• identified the controller class

• created a controller instance

• prepared request state

• made params available

At first glance, the next step seems simple:

call the action method

But there is still one more layer that matters a lot in real applications.

Callbacks.

Your action runs inside a callback chain.

The simplified shape looks like this:

before_action ⭢ action ⭢ after_action

That means the controller action is not an isolated Ruby method call. It runs inside a framework-managed pipeline that can prepare the state before the action and react after it.

Sometimes the thing affecting the request happened before the method you are looking at ever started.

Why before_action Order Matters

before_action is a good example of how dispatch gives Rails structure and also hides some visibility.

Suppose you have:

class UsersController < ApplicationController
  before_action :authenticate_user!
  before_action :load_user

  def show
  end

  private
 
  def authenticate_user!
    redirect_to login_path unless current_user
  end

  def load_user
    @user = User.find(params[:id])
  end
end

This looks straightforward, but the order matters.

The authenticate_user! redirects, Rails can halt the normal path before the action runs. Depending on the callback setup, later callbacks may not behave the way you expected either.

Callback order is part of request execution, not decoration around it.

If something feels wrong in a controller, it is not enough to ask only what the action does.

Also ask:

• which callbacks ran first?

• did one of them redirect or render early?

• did the action run at all?

Then Rails Invokes the Action Method

Once the callback chain has reached the action, Rails finally invokes the method corresponding to the action name. So if dispatch resolved:

controller: "users"
action: "show"

Rails eventually executes the show instance method on the fresh UsersController instance created for the request.

That method call is the result of a sequence, not the whole story.

By the time Rails gets there, the request has already passed through:

• middleware

• routing

• controller resolution

• request-context setup

• params assembly

• callback execution

Rendering vs Returning

There is one more controller misconception worth clearing up here.

Many Ruby methods are understood mainly through their return value. Controllers are different.

In Rails, what matters most is not the action’s final Ruby expression. What matters is whether the action performs a response.

That response might happen through:

• render

• redirect_to

• head

• or implicit rendering when Rails chooses a template for you

The controller action does not “return HTML” directly. It performs a response.

That is why an action can end with something like:

def show
  @user = User.find(params[:id])
end

and still produce a response through implicit rendering.

It also explains why this:

def show
  return "hello"
end

doesn’t mean what a normal Ruby method return would suggest in a controller context.

Rails is not treating your action like an ordinary function whose final value becomes the HTTP response body.

It is treating the action as one step in a controller dispatch and response-building process.

A Simple Dispatch Diagram

Here is the whole controller-dispatch path in one view:

Matched route

controller + action identified
  ⭢
controller instance created
  ⭢
params and request context prepared
  ⭢
before_action chain
  ⭢
action method
  ⭢
render/redirect/performed response

And the callback portion in isolation:

before_action ⭢ action ⭢ after_action

A Real Debugging Scenario

Let us make this practical with one example.

Suppose you are debugging a controller and asking: Why is my before_action not running?

The first instinct is often to open the controller and stare at the callback declarations. Sometimes that is the right place.

But sometimes, the issue is earlier in dispatch:

• the route matched a different controller than you expected

• the request never reached this action

• another callback halted execution earlier

• the action name was different from what you thought

Or take another question: Why is params[:id] missing?

Again, the problem may not be inside the action at all.

It may be:

• the route pattern was different from what you assumed

• the request matched a different route

• the expected value was in the query string instead of the path

• the request body did not parse the way you thought

When something feels wrong in a controller, the issue is often earlier in dispatch.

Why Rails Is Designed This Way

This dispatch layer exists because Rails is trying to separate several concerns that would otherwise blur together:

• route recognition

• controller resolution

• request preparation

• callback execution

• response handling

That separation gives Rails a lot:

• structure

• extensibility

• a place for callbacks

• a place for request setup

• a controller abstraction that feels consistent

But it also creates distance between “I matched a route” and “my code ran.”

You gain structure, but you lose some visibility.

The Final Mental Model

Routing decides where a request should go. Dispatch decides how that request gets executed.

The full flow now looks like this:

Request
  ⭢
Middleware
  ⭢
Dispatch
  ⭢
Controller
  ⭢
Response
  ⭢
Middleware
  ⭢
Client

And inside dispatch, the shape is:

matched route
  ⭢
controller resolved
  ⭢
controller instantiated
  ⭢
params prepared
  ⭢
callbacks run
  ⭢
action executed
  ⭢
response performed

Internally, Rails uses ActionController’s dispatch mechanism to orchestrate this sequence, but you do not need to understand those classes to reason about how requests flow.

Once you understand dispatch, the controller is no longer the starting point.

It becomes one step in a larger system.

That brings us to the router.

Once a request makes it through middleware, Rails still has to answer a simple question before any controller action can run: Where does this request go?

That sounds obvious when the route is small and familiar. You write get "/users/:id", to: "users#show", the request comes in, and Rails dispatches to UsersController#show. But the more time you spend in real Rails applications, the more routing starts to carry real weight. A route file stops being a small list of declarations and starts deciding which requests exist, which controllers see them, which params get extracted from the path, which HTTP verbs are allowed, and in what order all of those decisions are made.

By the end of this article, you should be able to answer this question clearly:

How does Rails take an incoming request and decide which controller action should handle it?

Start With the Right Mental Model

The cleanest mental model for Rails routing is this:

Routing is a pattern matching plus dispatch.

An incoming request reaches the router with a method, a path, and some request metadata. The router compares that request against the routes you defined in config/routes.rb. When it finds the first matching route, it extracts any dynamic segments from the path, builds the route params, and dispatches to the target endpoint.

So for a request like this:

GET /users/42

and a route like this:

get "/users/:id, to: "users#show"

Rails recognizes that:

• the HTTP verb is GET

• the path pattern matches /users/:id

• the dynamic segment :id has the value "42"

• the endpoint is UsersController#show

So the router hands off control with route params that include: { id: "42" }

It decides where the request goes.

Here is the routing flow in its simplest, useful form:

Incoming request (verb + path)
        ↓
Router scans the route set in order
        ↓
First matching route wins
        ↓
Dynamic segments become params
        ↓
Controller action dispatch

What the Router Actually Receives

By the time a request reaches the router, Rails has already done some work around it. The app server received the raw HTTP request. Rack defined the application interface. Middleware may already have assigned a request ID, parsed cookies, loaded the session, or even stopped the request early.

If the request survives that path, the router sees something much closer to an application-level request.

But the router is still not thinking in terms of models or views. It is looking at a smaller set of questions:

• What HTTP method is this request using?

• What path did the client ask for?

• Do any route constraints apply?

• Which route matches first?

• What dynamic values should be extracted from the path?

• Which controller action or Rack endpoint should receive the request?

Routing is not about “what the request means” in a business sense. It is about recognition and handoff.

config/routes.rb Builds the Route Set

When you define routes in Rails, you are not writing imperative code that runs for every request. You are declaring the route set that Rails will use later to recognize requests and generate URLs.

That route set usually lives in config/routes.rb.

A small example might look like this:

Rails.application.routes.draw do
  root "home#index"

  get "/users/:id", to: "users#show"
  post "/users", to: "users#create"
end

This file defines the shapes of requests that your application can recognize.

The route file is part of your application’s public surface area. It says:

• these URLs exist

• these HTTP verbs are valid for them

• these requests map to these endpoints

Routes define how the outside world enters your system.

Resourceful Routing Is a DSL Over Concrete Routes

Most Rails applications lean heavily on resourceful routing.

Your write:

resources :users

and Rails expands that into a set of concrete routes for the standard CRUD actions.

Conceptually, that single line becomes something like:

GET     /users            -> users#index
GET     /users/new        -> users#new
POST    /users            -> users#create
GET     /users/:id        -> users#show
GET     /users/:id/edit   -> users#edit
PATCH   /users/:id        -> users#update
PUT     /users/:id        -> users#update
DELETE  /users/:id        -> users#destroy

The resources DSL feels high-level, but the router still matches concrete route patterns.

Resourceful routing is a compact way to generate a predictable set of routes.

Route Order Matters More Than Many People Expect

One of the most important properties of the Rails router is also one of the easiest to miss:

The router uses the first route that matches.

That means order is behavior.

Suppose your routes look like this:

get "/users/:id", to: "users#show"
get "/users/new", to: "users#new

At first glance, both routes seem valid. But the order is wrong.

For a request is like:

GET /users/new

the first route also matches, because "new" can be captured as :id.

So Rails routes the request to UsersController#show with:

{ id: "new" }

The correct order is:

get "/users/new", to: "users#new"
get "/users/:id", to: "users#show"

That follows directly from the router’s model.

Dynamic Segments Become Route Params

When a route includes dynamic path segments, Rails extracts those values from the path and makes them available as route params.

For example:

get "/users/:id", to: "users#show"

paired with:

GET /users/42

produces:

{ id: "42" }

If the route contains more than one dynamic segment, Rails extracts all of them:

get "/accounts/:account_id/users/:id", to: "users#show"

with:

GET /accounts/7/users/42

becomes:

{ account_id: "7", id: "42" }

Path params are born in the router.

By the time the request reaches your controller, those values have already been extracted from the URL and merged into the request’s params structure.

Namespaces and Nested Routes Change the Shape, Not the Core Model

As route files grow, you start seeing things like:

namespace :admin do
  resources :users
end

or:

resources :accounts do
  resources :users
end

These can make routing feel more abstract, but the recognition model has not changed.

Namespacing changes the URL prefix and the controller target.

Nesting changes the path shape and gives the router more dynamic segments to extract, such as :account_id.

But in both cases, Rails is still doing the same job: matching the request against a concrete route set and dispatching to the first matching endpoint.

The Router Also Generates URLs, But That Is a Separate Direction

The Rails router has a second major responsibility: It generates paths and URLs through helpers like users_path(@user).

That matters a lot in real applications, but it is a different direction of travel.

In this article, we are focused on incoming request recognition:

Request → route match → controller action

URL generation works in the opposite direction:

Application code → router helper → URL/path string

These two responsibilities reside in the same routing system, but they are not the same.

For now, the important idea is that when an incoming request reaches the router, Rails solves a recognition problem before it does anything else.

The HTTP Vert Is Part of the Route

Developers often think of routes mostly in terms of paths, but Rails routes are defined by both the path and the HTTP verb.

These two routes are not the same:

get "/users", to: "users#index"
post "/users", to: "users#create"

They share the same path. They differ by method.

That means:

GET /users

and:

POST /users

are different requests from the router’s perspective, even though the URL path is identical.

This is one reason resourceful routing works so well for CRUD. Rails can reuse the same path shape while dispatching to different actions based on the HTTP verb.

It is also why route bugs sometimes appear when forms, JavaScript requests, or proxies send a method you were not expecting. If the verb does not match the route, the route does not match the request.

Query Parameters Are Not Usually What the Router Matches On

The router mainly matches on the request path and the HTTP verb.

So for a route like:

get "/users", to: "users#index

Both of these requests match the same route:

GET /users
GET /users?page=2&sort=name

The query string affects the request params your controller can read, but it does not usually determine which route matches.

Route definitions tend to describe structural path shapes rather than every possible filtering or pagination parameter.

There are advanced forms of request-based constraints, but the core mental model should stay simple:

The router mainly decides based on the method and path.

Routing Is the Boundary Between URL Shape and Controller Dispatch

Routing is the boundary where the external request shape becomes the internal application structure.

A route like:

get "/admin/reports", to: "admin/reports#index

does two things at once.

It defines the public URL shape.

It also defines an internal handoff to a controller namespace and action.

Routing choices influence:

• how obvious your application’s entry points are

• whether related endpoints feel coherent

• how much meaning is embedded in the URL structure

• whether controller boundaries stay understandable

The route file is not business logic, but it absolutely shapes the architecture around your application’s boundaries.

Where Routing Bugs Usually Come From

Once you understand the router as an ordered pattern matcher, several common bugs become much easier to explain.

Wrong action runs: Usually, a route higher in the file is matched first.

Expected path does not work: Often, the HTTP verb does not match the route definition, or the path shape is different from what you assumed.

Unexpected params: Often, a dynamic segment captured part of the path you did not realize it could capture.

Specific route never seems to run: Often, a more general route appears above it and absorbs the request first.

Nested controller gets surprising IDs: Those values usually come directly from route segments like :account_id or :project_id.

The router is deterministic. When routing feels strange, your mental model of the route set usually does not yet match the actual one.

How to Inspect What Rails Thinks the Routes Are

When route behavior feels confusing, do not guess. Inspect the route set.

bin/rails routes
bin/rails routes -g users

These let you see the concrete routes Rails built from your DSL.

That matters especially when you are using:

• resources

• namespaces

• nesting

• concerns

• custom member or collection routes

• constraints

The route file can look elegant while still producing a route set you did not fully anticipate. Inspecting the actual routes closes that gap.

A Request Through the Router

Let us trace one request cleanly from the router’s point of view:

GET /users/42

Suppose the route set contains:

get "/users/new", to: "users#new"
get "/users/:id", to: "users#show"

The router checks the request against the route set in order.

First route:

GET /users/new

That doesn’t match /users/42

Second route:

GET /users/:id

That does match.

Rails extracts:

{ id: "42" }

and dispatches to:

UsersController#show

In route definitions, Rails expresses the target as "users#show": controller "users", action: "show". During dispatch, Rails resolves that controller path into UsersController, so the request ultimately lands in UsersController#show.

At that point, the router’s main job for this request is done.

The request moves into controller dispatch with a chosen endpoint and a set of route params.

The Final Mental Model

The Rails router is the decision point between a request surviving middleware and a controller action beginning to run.

Its job is simpler than people sometimes imagine, but also more important.

It receives an incoming request.

It compares that request against the route set.

It finds the first route that matches the method, path, and any relevant constraints.

It extracts dynamic path values into route params.

It dispatches to the target endpoint.

Routing is not “just URLs.” It turns an external request shape into an internal application handoff.

So when you think about Rails routing, keep the model small and precise:

Routing is pattern matching plus dispatch.

Order matters.

Dynamic segments become params.

HTTP verbs are part of the route.

And by the time your controller starts running, the router has already decided both where the request goes and which path data accompanies it.

Once you see routing that way, config/routes.rb becomes visible, an inspectable boundary between the web and your application code.

When Rails behaves in a way that is hard to explain from the controller alone, middleware is often somewhere in the story. A request gets redirected before your action runs. A session appears to exist before you touched it. A response leaves the app with headers you never set. A request never reaches the controller at all. None of that is random. The middleware stack is usually one of the first places where the explanation begins.

Most Rails developers know middleware exists. They’ve seen bin/rails middleware, they have seen classes like ActionDispatch::Cookies or Rack::MethodOverride, and they know these layers sit “somewhere before the controller”. That vague sense is not enough when you need to reason about the system.

By the end, you should be able to answer this question with confidence:

What exactly is happening inside the middleware stack, and how do individual layers affect my request and response?

Start With the Right Mental Model

The most useful place to start is with a correction.

Middleware is not a list of steps that Rails runs before your controller.

It is a set of nested wrappers around your application.

That changes how you think about the request lifecycle. If middleware were just a list of pre-controller steps, then it would only matter on the way in. But that is not how Rack works, and Rails middleware inherits its shape from Rack.

The better mental model looks like this:

Request
-> Middleware A
  -> Middleware B
    -> Middleware C
      -> Rails router/controller
    <- Middleware C
  <- Middleware B
<- Middleware A
Response

The request travels inward through the stack until it reaches Rails routing and controller dispatch. Then the response travels back out through those same layers in reverse order.

Middleware can change the request before your action runs, change the response after your action finishes, or stop the request before it ever reaches your routes.

Why Middleware Exists at All

Rails middleware exists because Rails is a Rack application.

Rack is the shared interface between Ruby web servers and Ruby web frameworks. Instead of Puma needing to understand every detail of Rails' internals, Rack provides a common contract. A Rack application is just an object that responds to call and returns a response in a standard shape.

That shape is small:

call(env) # => [status, headers, body]

You can write a complete Rack app in a few lines:

class HelloWorld
  def call(env)
    [
      200,
      { "Content-Type" => "text/plain" },
      ["Hello from Rack"]
    ]
  end
end

That app receives a request environment and returns a three-part response:

• a status code

• a headers hash

• a body

Rails is obviously much more sophisticated than that. It includes routers, controllers, rendering, sessions, cookies, callbacks, and much more. But underneath those abstractions, it still participates in the same Rack contract. At the server boundary, Rails is just another Rack app that can receive env and return [status, headers, body].

Middleware can wrap Rails because it speaks the same protocol as the application it wraps.

A Middleware Is Just a Rack App That Wraps Another Rack App

The Rack contract makes middleware concrete.

A middleware usually looks like this:

class ExampleMiddleware
  def initialize(app)
    @app = app
  end

  def call(env)
    @app.call(env)
  end
end

At first glance, this looks almost too simple to matter. But the whole stack lives inside that shape.

The @app object is the next layer inward. Sometimes that next layer is another middleware. Eventually, the innermost layer is the Rails route set, which leads to controller dispatch.

The real power of middleware comes from what happens around @app.call(env):

class ExampleMiddleware
  def initialize(app)
    @app = app
  end

  def call(env)
    # work on the way in

    status, headers, body = @app.call(env)

    # work on the way out

    [status, headers, body]
  end
end

Anything before @app.call(env) runs while the request moves inward.

Anything after @app.call(env) runs while the response is still moving outward.

So when people say middleware runs “before the controller”, that is only half true. Middleware also runs after the controller. More precisely, middleware surrounds the controller and the rest of the Rails application.

What the Stack Is Actually Doing on the Way In

Before the request reaches your controller, middleware layers can inspect it, annotate it, normalise it, reject it, or route it elsewhere.

At the Rack level, the request is represented as env, a mutable hash containing request data and Rack-specific values. Early middleware sees a more raw version of the Request. Later middleware may see a richer request because earlier layers have already added information to env.

Middleware layers are not isolated from one another. They cooperate by working on the same request state.

For example, one middleware might assign a request ID:

class RequestIdMiddleware
  def initialize(app)
    @app = app
  end

  def call(env)
    env["my_app.request_id"] = SecureRandom.uuid
    @app.call(env)
  end
end

Anything deeper in the stack now reads that value. Middleware prepares the request so that later layers, including your controller, can rely on a richer set of assumptions.

In a real Rails stack, middleware commonly handles concerns like:

• assigning request IDs

• parsing cookies

• loading session state

• applying HTTP method overrides

• validating hosts

• resolving the client IP

• serving static files

• setting up framework-level request context

By the time your controller action runs, a lot of work has already happened. Controller-level reasoning can be incomplete when you debug a request. The request did not begin at the controller boundary. It arrived there after several other layers had already shaped it.

What the Stack Is Doing on the Way Out

Once the controller and the rest of the inner application return a response, the stack does not disappear. The response still has to travel back outward through the same middleware chain.

That means middleware can still change what the client ultimately receives.

A simple example looks like this:

class SecurityHeaders
  def initialize(app)
    @app = app
  end

  def call(env)
    status, headers, body = @app.call(env)

    headers["X-Content-Type-Options"] = "nosniff"
    headers["Referrer-Policy"] = "strict-origin-when-cross-origin"

    [status, headers, body]
  end
end

The controller doesn’t need to know this middleware exists. It renders the response it wants to render. Then middleware adds behavior that belongs at the edge of the application rather than inside a specific controller action.

Cookies may be written after the controller runs. Session changes may be committed after the controller runs. Logging may finish after the controller runs. Cache-related headers may be added after the controller runs.

So the response your controller builds is often not the final response the client receives. It is the inner response. Middleware may still wrap it, adjust it, and pass it outward.

Middleware Can End the Story Early

There is another piece of the middleware behavior that matters a lot in practice: a middleware doesn’t have to call the next layer at all.

It can return a response directly.

class MaintenanceMode
  def initialize(app)
    @app = app
  end

  def call(env)
    if ENV["MAINTENANCE_MODE"] == "true"
      [
        503,
        { "Content-Type" => "text/plain" },
        ["Maintenance mode"]
      ]
    else
      @app.call(env)
    end
  end
end

If this middleware returns that 503 response, the request never reaches the router. No controller runs. No view renders. The stack simply returns a response from that point.

This is called short-circuiting.

Static file middleware can serve files directly from public without ever involving your controllers. Host authorisation middleware can reject a request before routing. SSL enforcement can redirect a request before your application code executes. In all of these cases, the request stops moving inward because one layer has already decided what the response should be.

One of the most useful debugging questions in Rails is not “why did my controller do this?” but “Did the request even reach my controller?”

Middleware is often where that answer lives.

Why Order Matters So Much

Once you start thinking in terms of nested wrappers, middleware order becomes part of the design.

Suppose the stack looks like this:

use A
use B
run app

This is effectively:

A.new(B.new(app))

So A sees the request before B, but B sees the response before A.

That means the same middleware components can produce different behavior when you reorder them.

Take logging and exception handling as a simple example. If logging wraps exception handling, it may see the final 500 response produced by exception handling. If exception handling wraps logging, then the logger may never reach its normal “after” path unless it uses ensure. Same pieces, different order, different outcome.

Or think about sessions and cookies. Session behavior depends on cookie behavior. If you move or remove the cookie layer incorrectly, problems often appear later, in places that seem unrelated to the middleware itself.

Middleware order determines what state exists at each point in the request, what work can be wrapped, and what behavior can be observed on the way back out.

bin/rails middleware does not just show you a list of implementation details. It shows you the shape of the application boundary.

How to Read bin/rails middleware

When Rails prints the middleware stack, it is tempting to read it as a checklist.

Do not read it that way.

Read it as a set of wrappers.

If the stack says:

use OuterMiddleware
use InnerMiddleware
run Rails.application.routes

then you should mentally translate it into:

OuterMiddleware sees the request first.
InnerMiddleware sees the request after that.
Rails routes run inside both
InnerMiddleware sees the response first.
OuterMiddleware sees the response last.

That translation is enough to make the output useful.

You don’t need to memorise every default middleware in Rails to reason well about the stack. But you need to understand what kinds of layers you’re looking at and what role they play.

In practice, three questions help:

1. Which middleware can change the request before routing?

2. Which middleware can return a response before routing?

3. Which middleware can change the response after the controller?

Those questions cover most of the surprises.

Trace One Request Through the Stack

Let us make this concrete with a simple request:

GET /users/42

The app server receives the HTTP request and hands it to the Rails Rack app.

The request enters the middleware stack.

An early middleware may reject the host if the request came in for the wrong domain. Another may assign a request ID. Another may determine the client's IP. Another may parse cookies. Another may load the session. Another may wrap the inner app for logging or exception handling.

If no middleware stops the request, Rails routing finally receives it and matches it against something like:

get "/users/:id", to: "users#show"

Rails dispatches to UsersController#show, the action runs, and Rails builds a response.

Now the response heads back out.

The session layer may persist changes. Cookie middleware may add Set-Cookie headers. Logging middleware may finish recording the request. Response-handling middleware may add headers or adjust cache behaviour.

Finally, the outermost layer returns the response to the server, and the server sends it back to the client.

If you compare that to the simplified mental model many people carry around, the difference becomes obvious.

The request did not go straight from the URL to the controller.

The response did not go straight from the controller to the browser.

Both travelled through a stack of boundary layers that could shape the result at each step.

Why This Matters in Real Rails Work

A lot of unexpected Rails behavior becomes easier to explain once you know which layer owns it.

Request IDs make sense because middleware can assign request-wide state before the action runs. Sessions make sense because middleware can load and later commit session data around the controller. Cookies make sense because middleware can parse them on the way in and write them on the way out. Static files bypass controllers because middleware can short-circuit the request early. Response headers appear “by themselves” because middleware can still modify the response after rendering.

Instead of asking, “Why did Rails do this?” you start asking, “Which layer owns this behavior?”

Rails is not one thing. It is a composed system. Middleware is one of the most important places where that composition becomes visible.

The Final Mental Model

A Rails middleware stack is a chain of Rack applications wrapped around your Rails app.

Each middleware receives the request as env.

Each middleware can inspect or modify that request before calling the next layer.

Each middleware receives the response when the inner app returns.

Each middleware can inspect or modify that response before passing it back outward.

Any middleware can stop the request early by returning a response directly.

And the order of the stack determines what each layer can see, change, and wrap.

That means a Rails request is not:

URL -> Controller

It is:

Request -> Middleware stack -> Router -> Controller -> Response -> Middleware stack -> Client

Once you see the stack that way, middleware becomes part of the architecture you can inspect, reason about, and debug with confidence.

Your controller action runs. A response comes back.

But what happens before that?

That gap is where request behavior becomes hard to explain.

You know the URL.

You know the controller.

You know what gets rendered.

But before your action runs, Rails moves the request through several layers:

• the app server hands the request to Rails

• middleware processes it

• the router decides where it goes

• the controller action runs

• the response travels back through the stack

Most of that stays invisible - until something breaks.

This article makes that flow visible.

By the end, you should be able to answer one question clearly:

What exactly happens between an HTTP request hitting my app and my controller action running?

The Mental Model

Here is the shortest accurate version:

App server → Rails Rack app → middleware → router → controller → response → middleware → client

A Rails request is not a direct jump from URL to controller. It is a pipeline.

We will walk through that pipeline by tracing a single request:

GET /users/42

The Full Request Flow

Keep that diagram in mind as we trace the request.

Our example request comes in:

GET /users/42

Now let’s follow it, step by step.

1. The Request Reaches Your Rails App

Before Rails routing, controllers, or views are involved, something has to receive the raw HTTP request.

That job belongs to the app server.

In development, that might be Puma. In production, it is still a Rack-compatible server sitting in front of your Rails application.

The app server receives the HTTP request and invokes your Rails application as a Rack app.

That is the first key mental model.

Rails is a Rack application. Everything Rails does builds on top of this contract. At the lowest level, Rack defines a very small interface:

call(env) # => [status, headers, body]

That means a Rack app receives request data through env and returns a response as:

• a status code

• a headers hash

• a body

A minimal Rack app looks like this:

class App
  def call(env)
    [200, { "Content-Type" => "test/plain" }, ["Hello World"]]
  end
end

Rails is much more sophisticated than that, but it still plugs into that exact same contract. Underneath controllers, helpers and render methods, your Rails app is still just something that responds to call(env).

2. The Request Enters the Middleware Stack

Once the app server invokes the Rails Rack app, the request enters the middleware stack.

A lot of Rails behavior starts here.

Middleware is a chain of Rack applications wrapped around your app. Each middleware layer can:

• inspect the request

• modify the request

• stop the request early

• pass the request to the next layer

• inspect or modify the response on the way back out

So the shape is not:

Request → Rails somehow → Controller

It is:

Request →
  Middleware A →
    Middleware B →
      Rails endpoint →
    ←
  ←
Response

Each layer wraps the next, as nested function calls.

Some middleware examples:

• logging

• static file serving

• cookies

• sessions

• method overrides

• error handling

• response headers

By the time the request reaches your controller, it may already have been inspected, modified, or even short-circuited by several layers.

Sometimes, the thing you think Rails is doing in your action actually happens before the router even runs.

3. The Router Decides Where the Request Goes

If the request makes it through the middleware, it reaches the router. Now Rails needs to answer a simple question:

Which controller action should handle this request?

Suppose you have this route:

get "/users/:id", to: "users#show"

Our request is:

GET /users/42

The router pattern-matches the request path against the route definition. It sees that:

• the path matches /users/:id

• the dynamic segment is 42

• the target is UsersController#show

So Rails now knows where to dispatch the request, and it builds the params needed for that action:

{ id: "42" }

Routing is pattern matching plus dispatch.

It is not business logic.

It is not rendering.

It is not querying the database.

It is the decision point that says, “this request goes here.”

4. Rails Instantiates the Controller and Runs the Action

Once routing has selected the endpoint, Rails can hand off control to the controller layer.

For our example, that means instantiating UsersController and calling show.

At that point, the request has been transformed from a raw HTTP request into Rails-friendly abstractions.

Inside the controller, you work with things like:

• params

• request

• session

• cookies

• render

• redirect_to

A simplified controller might look like this:

class UsersController < ApplicationController
  def show
    @user = User.find(params[:id])
    render :show
  end
end

Most Rails developers are comfortable at this layer, which is why it is easy to treat the controller as the beginning of the request lifecycle.

But it is not the start of the story. The controller is a late stage in the pipeline.

By the time your action runs:

• the app server has already accepted the HTTP request

• Rack has already defined the interface Rails is using

• middleware has already had a chance to inspect or alter the request

• the router has already decided where the request belongs

5. Rendering Produces a Response

Once the action finishes, Rails turns that result into a response. That response might come from:

• rendering a template

• redirecting

• returning JSON

• sending just headers and a status code

However it is produced, the end result still has to fit the Rack response shape:

[status, headers, body]

So even though Rails gives you higher-level tools like render and redirect_to, it eventually converts everything back into the same low-level response structure.

Rails abstractions are built on top of a very small protocol.

6. The Response Travels Back Out Through Middleware

This part is easy to miss, but it is essential.

The response does not go directly from the controller to the browser. It goes back through the same layers that handled the request.

That means middleware can still change behaviour after your controller action has finished.

For example, middleware might:

• add headers

• write cookies

• log response details

• compress the body

• manage caching

• transform error responses

So the request lifecycle is not one-way. It is an in-and-out pipeline:

Request in → middleware → router → controller → response out → middleware

If you see a header you never set, or response behaviour you did not explicitly code in the action, middleware is one of the first places to look.

Where This Breaks in Real Life

Most surprising Rails behaviour comes from not knowing which layer owns the behaviour.

A few real debugging patterns:

• Unexpected redirect before your action runs: You expect UsersController#show to execute, but a middleware redirects the request before routing or controller dispatch happens.

• Session or cookie bugs: You inspect controller code looking for the problem, but the real issue is that session or cookie middleware is reading, writing, or rejecting request state earlier in the stack.

• Middleware ordering bugs: One middleware assumes another has already set something up. If the order is wrong, behaviour becomes inconsistent and hard to trace.

• Performance overhead before application code: You focus on controller and database time, but meaningful request cost is happening before the request even reaches the action.

When something feels mysterious in Rails, ask which layer owns the behaviour.

Very often, the answer is middleware.

The Final Mental Model

A Rails request is not:

URL → Controller

It is:

HTTP request
→ app server
→ Rails Rack app
→ middleware
→ router
→ controller action
→ router
→ middleware
→ client

Once you see that flow clearly, Rails stops feeling like a black box.

It becomes a system you can trace, debug, and reason about with confidence.