Diagnosing Turbo Drive Navigation Failures in Hotwire Applications

Recognizable Conditions

Turbo Drive replaces full page loads with fetch-based navigation, but several failure modes cause the browser to fall back to traditional navigation or behave unexpectedly. The most common symptoms are:

• Full browser reload instead of Turbo navigation
• Scroll position resets after navigation
• Form submissions fall back to full POST redirect
• Cached pages show stale data after mutations
• Third-party scripts re-initialize on every visit
• Redirects lose flash messages or session data
• Mobile Safari back/forward cache (bfcache) conflicts with Turbo Cache

Cause and Diagnostic Table

Symptom	Likely Cause	Quick Diagnostic
Full browser reload	Missing data-turbo="false" on links/forms, CSP blocking turbo:visit events, or JS errors halting Turbo listeners	Open DevTools Console: look for turbo:click/turbo:before-visit events. Network tab: check for Turbo-Visit request header.
Scroll position resets	Turbo Drive caches pages by default; data-turbo-action="replace" or advance changes history behavior. Turbo.cache.exemptPageFromCache() called or turbo:before-cache listeners mutate DOM incorrectly.	Inspect Turbo.cache.has(location.href) and verify no turbo:before-cache handlers alter scroll state.
Form falls back to full POST redirect	Missing Accept: text/vnd.turbo-stream.html header, server responds with HTML instead of Turbo Stream, or data-turbo="false" on form.	Network tab: check response Content-Type and presence of Turbo-Stream header.
Stale data after mutation	Turbo Cache retains previous body; missing turbo:before-cache cleanup or server not sending Vary: Turbo-Visit/Cache-Control: no-store for personalized content.	Run Turbo.clearCache() after mutation or add data-turbo-temporary to fragments; verify cache size via Turbo.cache.size.
Third-party JS re-initializes	Scripts in <head> execute once, but body scripts re-run on each visit.	Move initialization to turbo:load event or add data-turbo-eval="false" to script tags. Ensure Stimulus controllers use connect()/disconnect().
Redirect loses flash/session	Turbo follows redirects automatically but discards response body if not Turbo Stream. Server must return 303 with Turbo Stream or use turbo:before-visit to preserve flash via sessionStorage.	Check Turbo.session.drive configuration and response headers for Turbo-Location or Turbo-Redirect-To.
Mobile Safari bfcache conflict	Both caches restore pages differently; Turbo may restore stale DOM while bfcache restores JS state.	Add pagehide/pageshow listeners to call Turbo.cache.clear() or set Cache-Control: no-store on HTML responses. Test on real iOS Safari.

Ordered Diagnostic Checks

1. Verify Turbo Drive is enabled: In console, run Turbo.session.drive. If false, Drive is disabled globally.
2. Inspect a navigation request: Click a Turbo link. In Network tab, confirm the request includes Turbo-Visit: true header and the response includes Turbo-Location or Turbo-Redirect-To.
3. Trace visit lifecycle: Add document.addEventListener('turbo:visit', e => console.log(e.detail)) to see visit action (advance, replace, restore).
4. Check cache state: Run Turbo.cache.size and Turbo.cache.has(location.href) to confirm caching behavior.
5. Test with Drive disabled: Temporarily set Turbo.session.drive = false to isolate Turbo Drive vs. server issues.
6. Validate server responses: Use curl to simulate Turbo requests:

   curl -H 'Accept: text/vnd.turbo-stream.html' -H 'Turbo-Visit: true' <url>

   Should return Turbo Stream format (Content-Type: text/vnd.turbo-stream.html).

Fixes Tied to Findings

Full Reload

• Ensure no data-turbo="false" on links/forms unless intentional.
• Check CSP: script-src must allow 'unsafe-inline' or nonces for Turbo's inline handlers unless using custom delegate via Turbo.start().
• Fix any JavaScript errors that stop Turbo's event listeners (see console).

Scroll Reset

• Avoid calling Turbo.cache.exemptPageFromCache() unless necessary.
• Audit turbo:before-cache listeners: they must not mutate DOM in ways that lose scroll position.
• Use data-turbo-action="advance" (default) for normal navigation; replace only when you want to replace history entry.

Form Fallback

• Server must respond with Content-Type: text/vnd.turbo-stream.html for Turbo Stream responses.
• Ensure the form does not have data-turbo="false".
• Verify the request includes Accept: text/vnd.turbo-stream.html (Turbo adds this automatically).

Stale Cache

• Call Turbo.clearCache() after mutations that affect cached pages.
• Add data-turbo-temporary to fragments that should not be cached.
• For personalized content, send Vary: Turbo-Visit and Cache-Control: no-store from the server.

Third-Party Script Re-initialization

• Move initialization code into a turbo:load listener.
• Add data-turbo-eval="false" to script tags that should not be re-evaluated.
• Stimulus controllers: use connect() for setup and disconnect() for teardown.

Redirect Flash Loss

• Return a Turbo Stream response with a turbo-stream action that updates the flash container.
• Alternatively, store flash in sessionStorage via turbo:before-visit and restore on turbo:load.

Mobile Safari bfcache Conflict

• Add listeners:

  window.addEventListener('pagehide', () => Turbo.cache.clear());
  window.addEventListener('pageshow', (event) => {
    if (event.persisted) Turbo.cache.clear();
  });

• Or set Cache-Control: no-store on HTML responses (impacts performance).
• Always test on real iOS Safari; desktop responsive mode does not replicate bfcache behavior.

Escalation Criteria

Escalate when:

• Turbo.session.drive = false is set globally and cannot be changed.
• turbo:visit errors persist after verifying CSP, headers, and JavaScript errors.
• Turbo 8+ cache behavior changes (see Version Notes) cause regressions that cannot be resolved with configuration.
• Consider disabling Turbo Drive for specific routes via data-turbo-action="replace" or opting out of Drive entirely for problematic pages.

Version Notes and Limitations

• Turbo 8 (2024) changed cache defaults: Turbo.cache now uses PageSnapshot and CacheObserver. Older turbo:before-cache patterns may behave differently. Verify migration guide if upgrading.
• CSP script-src must allow 'unsafe-inline' or nonces for Turbo's inline event handlers unless using a custom delegate.
• Turbo Streams require Content-Type: text/vnd.turbo-stream.html; plain HTML responses to fetch/XHR will not trigger Stream actions.
• Do not mix Turbo Drive with legacy turbolinks; they share the global Turbo namespace and conflict.
• Mobile browsers may aggressively bfcache; test on real iOS Safari, not just desktop responsive mode.

Practical Verification Checklist

• DevTools Network: click a Turbo link → verify Turbo-Visit: true request header and Turbo-Location/Turbo-Redirect-To response headers.
• Console: Turbo.navigator.currentVisit during navigation to inspect visit state and action.
• Console: Turbo.cache.size and Turbo.cache.has(location.href) to confirm caching.
• Console: document.addEventListener('turbo:visit', e => console.log(e.detail)) to trace lifecycle.
• Temporarily set Turbo.session.drive = false to isolate Drive vs. server issues.
• Curl test: curl -H 'Accept: text/vnd.turbo-stream.html' -H 'Turbo-Visit: true' <url> returns Turbo Stream format.