Troubleshooting

Common issues and quick fixes for ashell.

Visual Issues, Freezing, or Rendering Problems

Problem: ashell may freeze, show visual artifacts, or fail to render properly on some systems.

Cause: Graphics driver compatibility issues. By default, ashell uses wgpu which uses vulkan as the default backend.

Rendering Backends

ashell supports two rendering paths:

1. wgpu (default) - Uses Vulkan by default. You can force a specific backend using the WGPU_BACKEND environment variable:

   WGPU_BACKEND=vulkan ashell  # Force Vulkan
   WGPU_BACKEND=gl ashell     # Force OpenGL/EGL

2. tiny-skia (CPU renderer) - Falls back automatically if wgpu fails, or can be forced with:

   ICED_BACKEND=tiny-skia ashell

Valid WGPU_BACKEND values

You can use a single value or a comma-separated list (e.g. WGPU_BACKEND=gl,vulkan). Values are case-insensitive.

Value	Aliases	Description
vulkan	vk	Vulkan API
gl	gles, opengl	OpenGL / OpenGL ES (EGL)

Backend Behavior

• ashell tries wgpu first, then falls back to tiny-skia if wgpu fails
• tiny-skia is a CPU renderer with less RAM consumption but potentially higher battery usage

If the issue persists: Try forcing a different backend or using ICED_BACKEND=tiny-skia.

Hybrid / Multi-GPU: Black Bar or Missing Bar on External Monitor

Problem: ashell renders a black bar, or the bar doesn't appear on all monitors. Common on laptops with hybrid graphics (e.g. NVIDIA dGPU + iGPU) or when an external monitor is connected to a different GPU.

Cause: By default, iced_layershell sets WGPU_POWER_PREF=low, which tells wgpu to prefer the integrated GPU. On hybrid setups, the iGPU may not be connected to all outputs, for example, an external monitor wired to the NVIDIA dGPU won't receive frames rendered on the iGPU. The result is a black bar or a bar that only appears on one screen.

Solution: Force the discrete GPU with:

WGPU_POWER_PREF=high ashell

To make it permanent, add to your compositor config. For Hyprland, in hyprland.conf:

env = WGPU_POWER_PREF,high

Note: WGPU_POWER_PREF is a regular process-level environment variable. Using Hyprland's env = propagates it to all wgpu-based applications (browsers, games, etc.), not just ashell. To limit it to ashell only, use exec-once instead:

exec-once = env WGPU_POWER_PREF=high ashell

Idle Inhibitor Issues

Problem: Screen sleeps even when ashell is running.

Cause: This is a swayidle bug in version 1.9.0+ with BlockInhibited property parsing.

Solutions:

• Downgrade swayidle to 1.8.x
• Wait for swayidle fix upstream
• Use alternative idle management tools like hypridle

Missing Tray Icons

Problem: Tray icons from some applications are missing when those applications start before ashell.

Cause: An application registers its tray icon (a StatusNotifierItem) with the org.kde.StatusNotifierWatcher that is running at that moment. Some applications only create their tray icon if a watcher already exists, and never check again. If such an application starts before any bar is running, there is nothing for ashell to find until the application restarts. This is a bug in those applications, not in ashell.

Restarting ashell while the application keeps running is a different case: the application's tray icon already exists, and ashell looks for existing icons when it starts.

Known examples:

• JetBrains Toolbox: if Toolbox starts before ashell, with no other bar running, its icon stays missing until Toolbox is restarted. See TBX-14742 (no tray icon on Arch with Plasma 6 on Wayland), TBX-12665 (Fedora 40 with GNOME, Toolbox has to be killed and restarted every time) and TBX-14468 (missing tray icon in awesomewm).
• Telegram: it does not re-register with tray services if ashell starts afterward.

Solutions:

• Start the affected application after ashell
• Restart the affected application after ashell has started
• Report the re-registration bug to the application's upstream tracker

Debug Mode

Run with debug logging to find issues:

RUST_LOG=debug ashell

Get Help

Include this info when reporting issues:

• OS and compositor
• GPU/driver info
• Full debug logs
• Your ashell config

Font Changes Don't Take Effect

Problem: Setting font_name in the config has no visible effect.

Cause: Most often, the font name doesn't exactly match the font's family name, or the font has a non-standard weight that causes a silent fallback.

Fix:

1. Verify the exact family name:

   fc-list | grep -i <search-term>

   Use the name shared by all weights ("Open Sans"), not a per-weight name like "Open Sans Light"; pick the weight with font_weight instead.
2. ashell prints warnings at startup when the font name is not found or when the weight doesn't match — check the logs.
3. Restart ashell after editing the config (font changes are not hot-reloaded).