OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
apps-services high common DISPUTE

Stop Ghostty dying with a SIGSEGV in its io thread by removing Omarchy's async-backend = epoll

omarchyarchghosttyhyprlandwaylanddesktoplaptop
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

Confirmed on this machine, omarchy 4.0.2-1 and omarchy-settings 4.0.2-1: async-backend = epoll is line 41 of /usr/share/omarchy/config/ghostty/config, pacman -Qo names omarchy-settings 4.0.2-1 as its owner, and diff shows ~/.config/ghostty/config byte-identical to the shipped file, so the migration claim holds. Also confirmed here that /usr/bin/omarchy-refresh-config copies the shipped file over the user one after saving $user_config_file.bak.$(date +%s), which is what the fix warns about. I read omacom/omarchy#6868 in full with comments: six reporters across 4.0.0rc5-1, 4.0.0-1, 4.0.1-1 and 4.0.2-1, all Ghostty 1.3.1-2, all the same io thread SIGSEGV at ghostty + 0x151c90d with r14 = 0 faulting on mov 0x108(%r14),%rcx, on NVIDIA, Intel xe and Panther Lake, with the herdr, OSC 4, idle and theme-reload triggers the symptom lists. The thread supports the claim. I verified the libxev source claims directly rather than trusting the thread: src/watcher/stream.zig:818 is const req_inner: *xev.WriteRequest = q_inner.head.?, src/backend/epoll.zig:380 guards submission with if (c.flags.state != .adding) continue while the dispatch callbacks at lines 432, 452 and 494 have no such guard, and test "pty: queued writes" skips itself with if (xev.dynamic and builtin.cpu.arch == .x86_64) return error.SkipZigTest. mitchellh/libxev#234 is open with no fix, and libxev main is still 9ce8e8e6 dated 2026-05-06, so nothing has landed. Two things were wrong in the fix and I rewrote it. First, the sentence "PR 7649 is not this one" cites omacom/omarchy#7649, which is a closed pull request titled "Fix Codex usage collection on 0.149" and appears nowhere in issue 6868 or pull request 6963, so it was misleading noise and is gone. Second, the release statement needed re-checking against a tag published after the record was written: v4.0.3 (2026-09-08) and the quattro branch both still carry the epoll line at line 41, which is stronger evidence than the pull request being open, so the rewritten fix states both and adds a grep to tell when the fix ships. Not exercised: Ghostty is not installed on this workstation (only foot 1.27.0-2), so I could not run the sed, reproduce the crash, or see the libxev manual backend=epoll startup line, and the verify block is unchanged but untested here.

The cause above was not rewritten and may still contain the error described. The fix below is the corrected version.

Symptom

Ghostty disappears, taking every window in the process with it. With the single-instance launch Omarchy uses (--gtk-single-instance=true) that is every terminal you had open, not one. It happens while typing, on an idle terminal, and on a theme switch.

coredumpctl shows the same fault every time, on six machines across four Omarchy releases:


kernel: io[493042]: segfault at 108 ip 000055eac209190d ... in ghostty[151b90d,55eac1d52000+88d000]

Thread io, SIGSEGV / SEGV_MAPERR, fault address 0x108, offset ghostty + 0x151c90d, instruction mov 0x108(%r14),%rcx with r14 = 0, build-id 36aeb61c844ddf428f960758acdb8b37f30d7e31.

Triggers reported, in order of how deterministic they are: launching a TUI that queries terminal capabilities at startup (herdr every time, on two machines, to the second), a tool issuing an OSC 4 palette query, plain shell-integration traffic on a terminal idle for 23 seconds after login, and a config reload from a theme switch.

Reported on Omarchy 4.0.0rc5-1, 4.0.0-1, 4.0.1-1 and 4.0.2-1, all with Ghostty 1.3.1-2, on NVIDIA, Intel xe and Intel Panther Lake graphics. One reporter's herdr client detached cleanly and its panes survived server side, so multiplexed work comes back and anything running directly in a surface does not.

Cause

Omarchy ships async-backend = epoll at line 41 of its Ghostty config and the migration copies it into your own, where it stays. Confirmed on an omarchy 4.0.2-1 install: the line is at line 41 of both /usr/share/omarchy/config/ghostty/config (owned by omarchy-settings) and ~/.config/ghostty/config. It was added as a workaround for slowness on Hyprland.

The epoll backend of libxev, which that setting selects, has a null dereference in its write path. The thread's source reading is against libxev rev 34fa5087, the revision Ghostty 1.3.1 pins: epoll.zig checks completion state when submitting but not when dispatching, so a dead completion still reaches its callback, and the write callback opens with const req_inner: *xev.WriteRequest = q_inner.head.? in stream.zig on a queue whose head and tail are both null. next sits at offset 0x108 of the epoll WriteRequest, which is the fault address. Upstream bug mitchellh/libxev#234, open since 2026-08-18 with no fix, and libxev's own queued-write test skips the x86_64 dynamic case as failing.

One reporter caught error(io_exec): write error: error.FileDescriptorAlreadyPresentInSet logged immediately before a crash, which is epoll_ctl returning EEXIST and cannot come from an io_uring backend, so the failing write was demonstrably in the epoll path. The second crash on that machine did not log it, so treat it as a co-symptom rather than a precursor.

Fix

Remove the setting from your own config. Do not edit the file under /usr/share/omarchy: it belongs to the omarchy-settings package and is not the file Ghostty reads.


grep -n 'async-backend' ~/.config/ghostty/config
sed -i '/^async-backend = epoll$/d' ~/.config/ghostty/config

Then quit every Ghostty window and start it again. The crash lives in the long-running single-instance process, so a reload is not enough to leave the epoll backend behind. Ghostty falls back to its default backend, which is what the reporter who found the deterministic herdr trigger did.

Two things to know afterwards. omarchy-refresh-config ghostty/config copies the shipped file back over yours, epoll line included, after saving your version as ~/.config/ghostty/config.bak.<epoch>, so if you ever run it you will need to delete the line again. And the removal is what upstream intends: omacom/omarchy#6963, "Remove unsafe Ghostty epoll workaround", was still open on 2026-09-11, and the newest tag v4.0.3 (2026-09-08) still carries async-backend = epoll at line 41 of config/ghostty/config, as does the quattro branch. A plain omarchy update therefore does not fix this yet. Check whether it has landed before editing by hand:


grep -n 'async-backend' /usr/share/omarchy/config/ghostty/config   # no output once the PR ships

If you would rather keep the workaround the setting was added for, there is nothing else in the thread to offer: libxev has no fix, mitchellh/libxev#237 was backported and measured in the issue thread without significantly reducing the crash rate, and Ghostty upstream asked for a debug build rather than more stripped 1.3.1-2 cores.

Verify


grep -c 'async-backend' ~/.config/ghostty/config     # 0
coredumpctl list ghostty                              # no new entry after the restart

Ghostty's startup log line info(gtk_ghostty_application): libxev manual backend=epoll is what the setting produces, so its absence is the direct check.

Sources

ghostty-epoll-backend-segfault-write-queue