A Rails 8.1 address book's contact frame shows 'Content missing' whenever a session expires mid-edit. Why does this happen, and how do you fix it?
answer
- redirect followed into the frame
- login page has no matching frame
- turbo:frame-missing, then TurboFrameMissingError
- turbo_page_requires_reload on the login view
- event.detail.visit(response)
basics
~20 sThe frame's request is redirected to the login page, which has no frame with the expected id, so Turbo fires turbo:frame-missing and writes Content missing. Mark the login page turbo-visit-control reload, or handle turbo:frame-missing with a full visit.
solid answer
~40 sWhen the session has expired, the Rails 8.1 authentication concern answers the frame's request with `redirect_to new_session_path`. `fetch` follows the redirect, and Turbo looks for `<turbo-frame id="contact_42">` in the login page. It is not there, so Turbo dispatches the cancelable `turbo:frame-missing` event on the frame; by default it then writes `Content missing` into the frame and throws `TurboFrameMissingError`. The simplest fix is to make the login page refuse to render in a frame: call turbo-rails' `turbo_page_requires_reload` in `sessions/new`, which emits `<meta name="turbo-visit-control" content="reload">`, and Turbo then performs a full-page visit with that response. Alternatively, a `turbo:frame-missing` listener can call `event.preventDefault()` and `event.detail.visit(event.detail.response)` to show any frame-less response as a page. Links that always leave the frame should carry `data-turbo-frame="_top"` instead.
code
erb · 8 lines<%# app/views/sessions/new.html.erb %>
<% turbo_page_requires_reload %>
<h1>Sign in</h1>
<%= form_with url: session_path do |form| %>
<%= form.email_field :email_address %>
<%= form.password_field :password %>
<%= form.submit "Sign in" %>
<% end %>go deeper
Know that Content missing means the response had no turbo-frame with the requesting frame's id.
Explain how a followed redirect lands a frame on a page without its id, and the two fixes: turbo_page_requires_reload on the target page and a turbo:frame-missing handler.
Separate policy from bugs: break out deliberately for authentication pages, keep handlers narrow so template id mistakes stay visible, and mind the stored return URL for frame requests.
Set an app-wide rule for which pages may never render inside a frame, so expired sessions and errors degrade to full pages consistently.
## What goes wrong In the address book, each contact row is `<turbo-frame id="contact_42">`. A user opens the edit form in place, goes to lunch, and comes back after the session has expired. Clicking **Save** sends the frame's form submission. The Rails 8.1 authentication generator's `Authentication` concern runs `require_authentication`, finds no session and calls `request_authentication`, which stores `request.url` for later and redirects to `new_session_path`. Inside the browser: 1. `fetch` follows the redirect transparently and receives the login page. 2. The frame looks for `turbo-frame#contact_42` in that page and finds nothing. 3. Turbo dispatches `turbo:frame-missing` on the frame. The event is cancelable and carries `detail.response` (the `Response`) and `detail.visit`, a function that performs a page-level visit. 4. If nobody cancels it, Turbo writes `<strong class="turbo-frame-error">Content missing</strong>` into the frame and throws `TurboFrameMissingError`, whose message suggests setting `turbo-visit-control` to `reload`. The user sees a broken row and no login form. The same happens to a lazy `src` frame whose request is redirected, and to any frame navigation that lands on a page without the frame: a 404 page, an error page, or a page rendered by a different template. ## Fix 1: the login page asks for a full reload Turbo checks every frame response for `<meta name="turbo-visit-control" content="reload">`. If it is present, the frame logs a warning and performs a **full-page visit** with the response instead of rendering into the frame. turbo-rails writes the tag with `turbo_page_requires_reload`: ```erb <%# app/views/sessions/new.html.erb %> <% turbo_page_requires_reload %> ``` The helper uses `provide :head`, so the layout must render `yield :head`. The generated Rails 8.1 layout does, and so does turbo-rails' minimal `turbo_rails/frame` layout. This is the fix the Turbo handbook recommends for expired sessions, because it is declared once, on the page that must never live in a frame. ## Fix 2: handle turbo:frame-missing For broader policies, a listener decides what a missing frame means: ```javascript document.addEventListener("turbo:frame-missing", (event) => { const { detail: { response, visit } } = event if (response.redirected) { event.preventDefault() visit(response) } }) ``` `visit` accepts either a URL or the `Response` itself; passing the response renders what was already fetched as a page, without a second request. Calling `preventDefault()` is what stops the default error handling. | Approach | Scope | Trade-off | |---|---|---| | `turbo_page_requires_reload` on the login view | one page | precise; every frame landing there escapes | | `turbo:frame-missing` handler | the whole app | flexible; can also hide genuine id mistakes | | `data-turbo-frame="_top"` on the link | one link | fine for links that always leave, no help for redirects | ## A detail of the return URL `request_authentication` saves `request.url` in the session so `after_authentication_url` can send the user back after signing in. For a frame request that URL is the frame's `src` or the form's action, not the page the user was on. After signing in, the user lands on that URL as a full page. Reasonable responses: - accept it when the frame URL is a full page in its own right, as Rails-style views usually are; - for non-GET requests, consider not storing it, since a submitted form's action URL says little about the page the user was on. ## Testing the fix The failure is easy to reproduce by hand: sign in, open a contact's edit form in its row, delete the session cookie in the browser's developer tools, then submit. With the fix in place the whole page shows the sign-in form and the console stays free of `TurboFrameMissingError`; without it, the row shows Content missing. Repeat the check for a lazy `src` frame, which takes the same path through the redirect. ## Distinguishing bugs from policy "Content missing" is also the symptom of a plain mistake: an edit view that forgot `turbo_frame_tag @contact`, or a frame id that differs between the index and the edit view. Before reaching for a global handler, check: - that the responding view renders a frame with exactly the requesting frame's id; - the browser console, where `TurboFrameMissingError` names the id and the response status; - whether the request was redirected, which points at authentication or authorization rather than templates. A global handler that turns every missing frame into a page visit makes template mistakes invisible, so many teams keep the handler narrow (redirects only) and rely on `turbo_page_requires_reload` for known pages.
- What does turbo_page_requires_reload do when a normal Turbo Drive visit, not a frame, reaches the login page?Drive sees `turbo-visit-control` set to `reload` and abandons the body swap in favour of a full browser load of the page. For a login page that is harmless, since it is a page users rarely navigate to repeatedly.
- Why should a turbo:frame-missing handler call event.preventDefault()?The event is cancelable, and Turbo runs its default handling only when it is not cancelled: writing Content missing into the frame and throwing `TurboFrameMissingError`. Calling `preventDefault()` stops that, so the handler's own `visit` is the only outcome.
- Turbo automatically breaks out of the frame whenever a frame request is redirected.
- Content missing means the server returned an error status for the frame request.
- turbo_exempts_page_from_cache on the login view makes frames escape to a full page.
- turbo:frame-missing cannot be cancelled; it is only a notification.
- Calling frame.reload() in a frame-missing handler will show the login page.
- A global frame-missing handler has no downside, so every app should add one.
Assumes Turbo 8 with turbo-rails 2.0.x and the Rails 8.1 authentication generator, whose request_authentication redirects to new_session_path.