Unofficial community reference. Not affiliated with 37signals or the Omacom Foundation. Download Omarchy only from omarchy.org.
omarchylinux.org Unofficial field manual

Thunderbolt and USB-C docks on Omarchy 4

What works and what breaks with Thunderbolt and USB-C docks on Omarchy 4.0.4: the early thunderbolt module, bolt authorization, DP alt mode wedges and fixes.

Partly works Applies to Omarchy 4.0.0 and later Last verified 2026-09-17 on 4.0.4
Short answer

Booting docked is the case that works in the reports; the trouble starts on undock, suspend or a monitor power cycle. Omarchy early-loads the thunderbolt module so dock displays live at the LUKS prompt, ships bolt for authorization, and re-syncs clamshell state on hotplug. The common failure is a DisplayPort alt mode path that stays dead. Suspend and resume or a VT switch clears many of these; the aquamarine 0.15.0 regression is fixed upstream in 0.15.1.

On this page
  1. Status on 4.0.4
  2. What Omarchy does automatically
  3. Known problems
  4. Fixes that work
  5. Report it
  6. Related

Thunderbolt and USB-C docks are one of the busiest problem areas in the Omarchy tracker. The search this page draws on returns 163 issues matching dock and Thunderbolt terms, but that pattern also catches Docker reports, so the real Thunderbolt volume is smaller. This page covers what was checked against the 4.0.4 source tree and the issues open on 2026-09-17.

Status on 4.0.4

Booting with the dock attached is the case that works in the reports here. On #11019 a docked boot and a hotplug from a clean boot both worked, on #10453 the dock monitors were up from firmware through to the desktop, and on #11908 the dock display worked until the first suspend. The failures cluster in one place: the DisplayPort alt mode path through a USB-C or Thunderbolt port, which can wedge after an undock, a monitor power cycle, or a suspend, and then refuse to come back until you reboot. The USB side of the same dock usually keeps working while video is dead, which is why these reports read like GPU bugs and are not.

The kernel-side failures below are not Omarchy-specific; reporters on #11864 and #10492 reproduced them on stock Arch kernels. What 4.x changed is the compositor side: Hyprland 0.56 with the aquamarine backend, and the aquamarine 0.14.0 to 0.15.0 package update that reached the stable channel around 2026-09-09 (#11019) is behind two of the worst current dock bugs.

What Omarchy does automatically

Four things, all confirmed in the 4.0.4 tree:

  • Early Thunderbolt in the initramfs. /etc/mkinitcpio.conf.d/thunderbolt_module.conf contains a single line, MODULES+=(thunderbolt). It was added by PR #1894 for issue #1893, where a BeeLink SER8 on a Dell WD22TB4 showed a black screen at the Plymouth login, and shipped in v3.2.3 on 2025-12-15. Without it, a display behind a dock is dark at the Plymouth and LUKS prompt.
  • bolt in the base package set. install/omarchy-base.packages lists bolt, so boltd and boltctl are present for Thunderbolt device authorization. No Omarchy script configures it further, so enrollment and security level follow upstream bolt defaults.
  • Monitor hotplug recovery. omarchy-hyprland-monitor-watch listens on the Hyprland socket for monitoradded and monitorremoved, re-syncs clamshell state three more times at one, three and seven seconds after each change, and runs a backoff loop that reloads Hyprland while any enabled output reports a 0x0 mode. omarchy-hw-external-monitors reads /sys/class/drm directly and ignores eDP, LVDS and DSI, so an external panel on a dock counts. omarchy-hw-recover-internal-monitor clears a stale internal-display-disable toggle when no external display is connected.
  • DDC/CI brightness. ddcutil is in the base list and 4.0.0 wired the brightness keys to the focused external display, so a dock-attached monitor that speaks DDC responds to the same keys as the laptop panel.

There is no dock-specific script in install/hardware/ and no omarchy-hw-thunderbolt. The omarchy-hw-* scripts that matter here are the clamshell and external-monitor helpers listed above.

Known problems

The recurring pattern is a Type-C port whose PD or alt mode state gets stuck. On the Dell XPS 16 DA16260 (Panther Lake, xe) and the XPS 15 9530 (i915) the kernel logs ucsi_acpi ... Firmware bug: duplicate partner altmode SVID 0xff01 and a VDO mismatch, the adapter enumerates as a USB billboard device, and the port stays at USB2 with no DRM connector (#11864). All three reporters there saw the same first VDO value, and one saw a byte-identical pair with two different monitors on all three ports, which points at the laptop’s firmware table rather than the monitor. On Meteor Lake the symptom after s2idle is ucsi_acpi ... GET_CABLE_PROPERTY failed (-5) with both partner alt modes inactive, and there a reboot was the only recovery (#11908). On two Tiger Lake machines /sys/class/typec is empty because ucsi_acpi never binds the USBC000 device at all (#9513, #10492).

A second pattern is compositor side. aquamarine 0.15.0 rejects a commit to an output the kernel already reports disconnected, but Hyprland only sends its disable commit after the disconnect, so the disable is dropped and the kernel CRTC stays active. On Intel that stale pipe pins the Type-C port and every modeset afterwards fails with EINVAL (#11019); on NVIDIA the failure is silent and the monitor just shows no signal (#11249). Reports cover i915, xe, amdgpu and nvidia-drm, and the trigger can be an undock, a monitor power button, or the lock screen’s blank. Upstream fixed it in hyprwm/aquamarine#410, merged 2026-09-15 and released as aquamarine 0.15.1 on 2026-09-17; Arch extra had 0.15.1-1 the same morning. The Omarchy issues are still open, and whether the stable mirror has synced it is something to check with pacman -Si aquamarine.

Known issues

Issue Models Status Fixed in
#1893 dock display black at LUKS/Plymouth BeeLink SER8 + Dell WD22TB4, Framework Desktop fixed v3.2.3
#10453 early thunderbolt module drops dock USB before LUKS GMKtec NucBox K8 Plus + Dell WD19TB open not yet
#11019 dock monitors never return after undock Dell XPS 9320, ThinkPad X1 Carbon Gen 11, MST docks on i915 open aquamarine 0.15.1 upstream, 2026-09-17
#11249 external monitor dead after power cycle ASUS Ryzen 9 8945HS + RTX 4060, desktop RTX 4080/4090 open aquamarine 0.15.1 upstream, 2026-09-17
#11908 monitor gone after suspend, reboot only Meteor Lake laptop (model not given), Genesys Logic USB-C dock open not yet
#11864 DP alt mode wedged until reboot or suspend Dell XPS 16 DA16260, XPS 15 9530 open not yet
#9513 ucsi_acpi never binds, no typec ports Framework Laptop 13 11th gen open not yet
#12207 USB4 monitor stuck at 640x480, corrupt EDID Dell XPS 16 + CalDigit TS5 or direct open not yet
#7328 display dark after long clamshell suspend Framework 13 AMD + CalDigit TS3 Plus open not yet
#8758 lid-closed boot on dock strands NetworkManager ThinkPad P16v Gen 3, Dell laptop + WD22TB4 open not yet
#10690 USB-C power blip fakes a lid close Dell XPS 14 DA14260 open not yet
#7388 Studio Display over USB4 flashes HP ZBook X G1i, Arrow Lake open not yet
#10638 pcie_ports=compat blocks dock PCIe tunneling MacBookPro13,2 (T1), reported on 4.0.0.alpha open not yet
#11926 no USB hotplug at all MacBook Pro 16-inch 2019, T2 open not yet
#8097 USB autosuspend drop-in has no effect all installs with the stock drop-in open not yet
#10492 DP alt mode dead until EC power drain Lenovo Yoga 14s ITL 2021 open not yet
#3918 shutdown restarts instead Framework Desktop (3.2.3 and 3.3.3 reports, none on 4.x) open not yet

Fixes that work

Try these in order. Stop when the picture comes back.

  1. Suspend and resume. This is the highest-yield step and the least obvious. On #11864 one reporter confirmed a roughly twelve-second suspend restored the display with the cable untouched and no firmware-bug message on the resume path; a second reporter on an XPS 15 9530 found suspend and logging out both worked while hyprctl reload did not. A HUAWEI MateBook X Pro reporter on #9513 got the same result and scripted it as sudo rtcwake -m mem -s 5. It does not help on #11908, where suspend is what breaks the port.
  2. Switch to a TTY and back. Ctrl+Alt+F2, then Ctrl+Alt+F1. Hyprland drops and reacquires DRM master, which releases a CRTC that aquamarine 0.15.0 left orphaned. Confirmed on #11019 and #11249, and on #7328 for monitors powered off overnight while the host stayed awake. It sometimes needs a second round, and one reporter had Chrome crash on the switch.
  3. Re-probe the connector. As root, echo off > /sys/class/drm/card0-DP-1/status, then echo on > and echo detect > into the same file, substituting your connector. On #12207 this recovered the full EDID on eight of eight failed hotplugs, and it is the basis of that reporter’s udev workaround for USB4 monitors that come up at 640x480. On #7328 detect on its own was a no-op after a long suspend; the off, on, detect sequence brought the monitor back within a second.
  4. Check whether video or the whole dock is gone. Run boltctl list and ls /sys/class/typec. If /sys/class/typec is empty, the Type-C stack never came up at all, which is #9513 and a kernel problem, not a display one. If boltctl shows the dock authorized but no DRM connector appears, you are in the alt mode wedge.
  5. If the failure started after the aquamarine 0.15.0 update, install 0.15.1. It reached Arch extra on 2026-09-17, keeps the 0.15.0 soname, so Hyprland and hyprtoolkit stay as they are, and one reporter on #11019 confirmed it on Meteor Lake over USB-C. Restart the session afterwards. If the stable mirror has not synced it yet, the alternative is downgrading to aquamarine 0.14.0, which means holding aquamarine, Hyprland and hyprtoolkit together because 0.15.0 bumped the library soname; #11249 has the exact package set.
  6. Pin a mode instead of using preferred, and expect only partial relief. The stock ~/.config/hypr/monitors.lua uses mode = "preferred", which on an Apple Studio Display picks 5120x2880@120 as the first EDID mode (#7388). Pinning 5120x2880@60 or 3840x2160@60 stopped that choice, but the reporter’s USB4 tunnel still dropped after about twenty seconds with failed to reach state TB_PORT_UP in the log, so this is not a complete fix on Arrow Lake. See the Monitors chapter and /hardware/multi-monitor/.
  7. Last resort for a truly dead port: full power drain. On #10492 the port stayed dead across reboots and shutdowns, and only came back after removing all cables and holding the power button for thirty to forty seconds.

Two Omarchy-side notes. If your dock keyboard is dead at the LUKS prompt, that is #10453 and there is no fix yet; use a directly attached keyboard. If you are on a T1 Touch Bar MacBook and the dock’s ethernet never appears, check /etc/limine-entry-tool.d/ for a file carrying pcie_ports=compat. The reporter on #10638 was on 4.0.0.alpha with a macbook-t1.conf; the 4.0.4 tree only writes t2-mac.conf, and neither the installer nor migration 1785944594 touches a T1 file. The reporter’s one-line sed replacing pcie_ports=compat with pm_async=off mem_sleep_default=deep, followed by limine-mkinitcpio and a reboot, made the dock’s ethernet enumerate.

Report it

Run omarchy debug, which in the 4.0.4 tree dispatches to omarchy-debug. Add --print to see the output without uploading, and --no-sudo to skip dmesg. Two reporters on 4.0.x builds (#7388, #12207) found the command missing; if that is you, collect the items below by hand.

A dock report is only useful with the parts the maintainers cannot guess. Include the dock model and the exact cable, boltctl list, ls /sys/class/typec and the contents of any portN-partner directory, the status of every /sys/class/drm/card*-*, and hyprctl monitors all -j. Capture journalctl -k -b filtered for ucsi, typec, thunderbolt and drm. Say explicitly whether the USB side of the dock still works while video is gone, and whether suspend and resume or a VT switch recovers it. That one sentence separates the alt mode wedge from the aquamarine regression faster than anything else.

Most-discussed upstream issues

The most-discussed upstream issues for this subsystem (206 total, 109 open).

IssueStateCommentsOpened
#1806 Macbook Pro 2020 WIFI Issuesopen342025-09-19
#849 Add display-tui for monitor setupclosed62025-08-16
#2903 Chromium Freezes When Pasting Clipboard Data From Windowsopen162025-10-27
#9334 Windows VM 4.0.2: launch fails silently after polkit auth (setgid chmod check can never pass)closed152026-08-31
#11019 External monitors on a USB-C dock never return after undocking (aquamarine 0.15.0 regression)open162026-09-09
#7909 Random hard reboots on ThinkPad X1 Carbon Gen 11 — Omarchy only, Ubuntu stableopen152026-08-23
#11249 aquamarine 0.15.0: external monitor never recovers after being turned off (NVIDIA repro), please hold or patch aquamarineclosed112026-09-10
#2202 Wifi does not work on Beelink SER9 PROclosed132025-10-04
#8328 nvidia.lua forces LIBVA_DRIVER_NAME=nvidia on hybrid laptops where the dGPU drives no displaysclosed122026-08-26
#4622 Some keybindings or even manual invocation of apps stopped workingclosed92026-02-16
#1893 Plymouth Login screen not showing on external monitor connected via Thunderbolt dock · fixed by #1894 closed102025-09-23
#11864 USB-C→HDMI DisplayPort Alt Mode negotiation fails and stays wedged until reboot (Panther Lake xe/ucsi_acpi)closed92026-09-14

Questions people ask

My dock's monitors are dead after unplugging and replugging. What do I do?
Suspend and resume the machine first, then try a VT switch (Ctrl+Alt+F2, then back). Suspend cleared the wedged Type-C state for two reporters on #11864 and one on #9513; the VT switch released the orphaned CRTC on #11019 and #11249. If the failure started with aquamarine 0.15.0, install aquamarine 0.15.1, which carries the upstream fix and needs no Hyprland rebuild.
Why does my dock keyboard not work at the LUKS passphrase prompt?
Omarchy early-loads the thunderbolt module so dock displays come up in Plymouth, but the dock cannot be authorized until boltd starts from the encrypted root. On docks whose USB ports sit behind a Thunderbolt PCIe xHCI controller, that removes the firmware-provided USB, as reported in #10453. Type the passphrase on a directly attached keyboard.
Do I need to run boltctl to authorize a new dock?
Possibly. Omarchy installs bolt in the base package set and nothing in the tree configures it, so you get upstream defaults. On #10453 the reporter ran boltctl enroll once, which restored the dock's USB immediately, and boltd re-authorized the stored dock automatically on every later boot. Run boltctl list to confirm a dock is authorized before blaming the display path.

Sources and credit

Fixes on this page were worked out by sgruendel (Found that the missing thunderbolt initramfs module blanked dock displays at the Plymouth prompt, and shipped the fix), davidisgeek (Traced dock keyboards dying at the LUKS prompt to the early thunderbolt module unbinding firmware-provided USB), jacobrosenthal (Identified the aquamarine 0.15.0 commit that leaves an orphaned CRTC after undocking), NikPiermafrost (Documented the ucsi_acpi partner PD state loss that kills DP alt mode across suspend), diazkev314 (Captured the failing USB4 EDID read with drm.debug and built a re-probe workaround), jeyrb (Found that a T1 MacBook still carried pcie_ports=compat, blocking dock PCIe tunneling). Text here is our own paraphrase; follow the links for the original threads.

Unofficial. Verify against the official manual for your version. Improve this page Markdown version Sources