Full page reload or manual DOM cleanup after a failed Turbo Stream upgrade?

The Recommended Recovery Strategy

To protect unsaved client-side state, avoid a full page reload. A full reload is the most reliable way to ensure DOM and asset consistency, but it destroys all non-persisted form data and volatile JavaScript state. Instead, use a combination of Turbo Frame snapshots for structural recovery and targeted data-attribute cleanup for orphaned elements.

Likely Explanation of the Conflict

Turbo Streams are additive or transformative; they do not operate as atomic transactions. If a stream response contains multiple turbo-stream elements and the connection drops or a server error occurs mid-processing, the browser may have already applied some changes. Because Turbo does not natively "roll back" the DOM to a previous state upon a 500 error, you are left with a partial update.

Implementation Steps for Safe Cleanup

To safely target only the nodes added by a failed stream without affecting concurrent updates, follow these steps:

1. Tag Streamed Elements: Ensure all elements delivered via Turbo Stream include a specific data attribute (e.g., data-turbo-stream-id="request-123") or a general marker like data-stream-generated.
2. Implement a Custom Error Handler: Use the turbo:visit:error or a global fetch interceptor to detect the failure.
3. Scoped Removal: Use a scoped selector to remove only the elements associated with the failed request ID.

   // Example: Remove elements from a specific failed request
   const failedElements = document.querySelectorAll('[data-turbo-stream-id="request-123"]');
   failedElements.forEach(el => el.remove());

4. Restore Frame Snapshots: If the failure occurred within a turbo-frame, trigger a reload of that specific frame to pull the last known good state from the Turbo cache, preserving the rest of the page state.

The Asset Versioning Limitation

There is no practical method to revert loaded CSS or JavaScript assets without a full page reload. Browser APIs do not support "unloading" a script or stylesheet once it has been executed or parsed into the CSSOM. If a failed upgrade has introduced mismatched asset versions, the application remains in a mixed-version state until a full reload occurs.

Diagnostic Requirement

To refine this recommendation: Are your Turbo Stream responses delivering multiple independent updates in a single request, or a single update to a single frame? If it is the latter, frame-level snapshots are sufficient; if the former, the data-attribute tracking mentioned above is mandatory.