RCA-2026-05-18-001: Prevention

Preventive Measures

Short-term (This Week)

Action Owner Status

Add oil to bypass_session_save_file_types in domus-nvim

Evan

[ ] Pending

Delete stale swap files and corrupted session file

Evan

[ ] Pending

Audit bypass_session_save_file_types for other missing filetypes (trouble, lazy, mason, toggleterm, Telescope)

Evan

[ ] Pending

Long-term (This Quarter)

Action Owner Status

Add pre_save hook to auto-session that closes all non-file buffers before saving (defense-in-depth beyond the bypass list)

Evan

[ ] Pending

Document plugin interaction matrix in domus-nvim: which plugins create special buffer types and how they interact with session management

Evan

[ ] Pending

Consider adding auto-session pre_restore hook that validates session file contents before sourcing (detect URI-scheme buffers, missing files)

Evan

[ ] Pending

Detection

How was it detected?

  • VimEnter error message displayed on every Neovim launch

  • User manually investigated after observing persistent errors

Detection Gap

The error was immediately visible — no detection gap for the symptom. However, the cause (oil buffer being saved into the session) happened silently at session save time with no warning. A pre_save hook that logs non-file buffer types being saved would have caught this at write time rather than restore time.

Lessons Learned

What went well

  • Root cause identified quickly — the error message pointed directly to the session file and line number

  • No data loss — swap files and session files are disposable artifacts

  • Fix is minimal and permanent (one string added to a Lua table)

What could be improved

  • New buffer-type plugins must be evaluated against session management at install time

  • The bypass_session_save_file_types list should be comprehensive from the start, not grown reactively

  • Killing Neovim (kill / kill -9) should be avoided in favor of :qa! to allow swap cleanup

Key Takeaways

  1. Session management is a cross-cutting concern. Any plugin that creates non-file buffers (file explorers, terminals, sidebars, dashboards) must be registered with auto-session’s bypass list. This is not optional — unrestorable buffers corrupt the session.

  2. Bypass list should be proactive, not reactive. Audit the list whenever adding a plugin that registers a custom filetype or creates URI-scheme buffers.

  3. Swap files are symptoms, not causes. Deleting swap files fixes the E325 prompt but not the underlying session corruption. Always investigate what created the swap file in the first place.

  4. Defense in depth: A pre_save hook that closes non-file buffers before session save is more robust than relying solely on a filetype bypass list, because it catches filetypes you forgot to add.

Related

  • Config: domus-nvim/lua/domus/plugins/specs/tools.lua:115-124 — auto-session setup

  • Config: domus-nvim/lua/domus/plugins/specs/tools.lua:56-86 — oil.nvim setup

  • Session: ~/.local/share/domus-nvim/sessions/ — session file storage

  • Swap: ~/.local/state/domus-nvim/swap/ — swap file storage