Troubleshooting

Debug Logging

Run zlaunch with verbose logging:

RUST_LOG=debug zlaunch

This outputs detailed information about configuration, compositor detection, IPC, and module initialization.

Error: Address already in use

A previous daemon didn't clean up. Remove the socket:

rm $XDG_RUNTIME_DIR/zlaunch.sock
zlaunch

Already running

Only one daemon can run at a time:

zlaunch quit
zlaunch

pgrep zlaunch

zlaunch show

echo $HYPRLAND_INSTANCE_SIGNATURE  # for Hyprland
echo $NIRI_SOCKET                   # for Niri

Unsupported compositor

Window switching requires Hyprland or Niri. KDE support is experimental. Other compositors fall back to no-op.

Socket permission issues

Verify you can access the compositor socket. Check $XDG_RUNTIME_DIR permissions.

Issue	Solution
Protocol not supported	Requires `wlr-data-control-v1` (KDE doesn't fully support)
Monitor not running	Check debug logs for clipboard errors

Check the .desktop file's Exec field—some apps have malformed entries.

Set $TERMINAL environment variable:

export TERMINAL=kitty

Add to your shell profile.

Apps inherit the daemon's environment. Restart daemon if you changed shell variables.

Issue	Solution
Theme not found	Check name matches exactly (case-sensitive)
Custom theme	Verify file is in `~/.config/zlaunch/themes/` with `.toml` extension
Invalid TOML	Validate syntax with a TOML checker

File location

Must be at ~/.config/zlaunch/config.toml (not ~/.zlaunch/config.toml)

Reload required

Most changes auto-reload. For major changes, run zlaunch reload.

Set explicit window size:

window_size = [1920.0, 1080.0]

This prevents allocating an 8K buffer on some compositors.

decoration:blur:enabled = true

hyprland_auto_blur = true

layerrule = blur on,match:class zlaunch
layerrule = blur_popups on,match:class zlaunch
layerrule = ignore_alpha 0.35,match:class zlaunch

Issue	Solution
No response	Verify API key is set in environment
Ollama not working	Ensure service is running, model exists (`ollama list`)
Wrong provider	zlaunch uses first configured: Ollama → Gemini → OpenAI → OpenRouter

If you can't resolve an issue: