Troubleshooting

First things to check when PlasmaZones misbehaves.

If nothing below helps, attach a support report to your bug on GitHub Issues. It bundles config, layouts, screen topology, and recent daemon logs with home paths redacted.

PlasmaZones not appearing in System Settings (KDE only)

KDE caches installed KCM modules. After a source install, the cache needs a rebuild before the new module shows up under System Settings › Window Management.

kbuildsycoca6 --noincremental

Logging out and back in triggers the same rebuild. The standalone settings app doesn't depend on the cache and is always available via plasmazones-settings.

Daemon not starting

PlasmaZones runs as a systemd user service (plasmazones.service). These three commands cover most cases:

# Status and recent log lines
systemctl --user status plasmazones.service


# Tail the full journal (Ctrl-C to stop)
journalctl --user -u plasmazones.service -f


# Restart after a config change or upgrade
systemctl --user restart plasmazones.service

If the service is reporting inactive (dead) and nothing obvious stands out in the journal, drop to verbose logging for more detail.

Capturing verbose logs

--debug turns on every plasmazones.* logging category at once; --log-file redirects output away from the journal so a single run is easy to attach to an issue.

# Stop the service so it doesn't race with the manual run
systemctl --user stop plasmazones.service


# Run the daemon in the foreground with full logs
plasmazonesd --debug --log-file /tmp/pz.log


# Reproduce the issue, Ctrl-C to stop, then restart the service:
systemctl --user start plasmazones.service

The log file is plain text. To scope down to one subsystem, grep by category: grep 'plasmazones.snapping' /tmp/pz.log.

Zones not appearing when dragging

Four things to check, most common first:

  1. The daemon isn't running. Check with systemctl --user status plasmazones.service and start it if it isn't active.
  2. The drag modifier doesn't match the setting. Default is Alt; the other configurable options are Meta, Ctrl+Alt, Alt+Shift, Alt+Meta, and Ctrl+Alt+Meta. Check Settings › Snapping › Activation, or see the shortcuts reference.
  3. The current layout has no zones. Open Meta+Shift+E to confirm; a layout with zero zones skips the overlay.
  4. The application is excluded. Apps on the exclusion list under Settings › Exclusions never trigger snapping. Class-based matches can occasionally catch a window you didn't mean to exclude.

Tiles not reaching their intended size

Some apps (Firefox, Chromium-based apps, Electron apps) enforce a minimum size that prevents PlasmaZones from tiling them at the target geometry. Fix it with a KWin Window Rule:

  1. Open System Settings › Window Management › Window Rules.
  2. Add a rule matching the window class. The eyedropper picker grabs the class from the misbehaving window.
  3. Under the Size & Position tab, set Minimum Size to Force 0×0.

Forcing 0×0 removes the app's minimum-size constraint for KWin, so PlasmaZones can tile the window at the size the layout asks for.

Generating a support report

When filing a bug, attach a support report. It bundles:

Home paths are redacted so you can attach reports publicly.

# Default: 30 minutes of logs, archive written to /tmp
plasmazones-report


# 60 minutes of logs (max 120)
plasmazones-report --since 60


# Write to a specific directory
plasmazones-report --output ~/Desktop

Or trigger the same collection over D-Bus:

qdbus6 org.plasmazones /PlasmaZones \
  org.plasmazones.Control.generateSupportReport 0

The D-Bus path is what the plasmazones-report CLI calls internally, and what scripting integrations should prefer. See the D-Bus scripting guide for the other interfaces and recipes.

Still stuck?