Documentation

Troubleshooting

Something feels off — the dock is gone, an extension stopped working, a game crashes, an app won't launch after an update. Most issues have a graphical fix in under a minute; the few that need a terminal are clearly marked. Work through the list top to bottom.

Always try this first — just restart

Activities → Power → Restart…. Half of the "weird GNOME behaviour" goes away with a clean shell restart. Costs you 30 seconds.

An extension or the dock looks wrong

Open Extension Manager (preinstalled). Toggle the affected extension off, then on again. If it still misbehaves, click the gear icon next to it and check the per-extension settings.

If the whole Margine look has drifted (dock missing, keybindings changed, app folders disappeared), restore the defaults from a terminal — single command:

ujust margine-bootstrap

Log out + log back in once it finishes.

An app won't launch / something broke after an update

Easiest path — boot the previous version:

  1. Activities → Power → Restart…
  2. As the machine boots, tap the ↑ / ↓ arrow keys to stop the GRUB auto-boot countdown and show the menu. (Don't press Esc — it drops into GRUB's command line, not the menu.)
  3. Pick Margine (previous). You're back on the previous OS image.

If that fixes it, please file a bug at margine-image issues so we can pin the bad release.

Check what state the system is actually in

A one-shot health check that prints a PASS/FAIL verdict line. Open Ptyxis (terminal in the dock) and run:

margine-validate-margine-system

It checks ostree layout, kernel signature, MOK enrolment, media stack, GNOME defaults, expected Flatpaks. Use this output as the body of a bug report — it tells the maintainer in 20 lines what's actually on your machine.

For more focused checks (slower but more detailed):

margine-validate-atomic-layout         # ostree, mounts, Secure Boot, TPM2
margine-validate-cachyos-kernel        # kernel version + signature + MOK
margine-validate-hardware-media-stack  # Mesa, Vulkan, VA-API, PipeWire
margine-validate-gaming-runtime        # gaming layer (if installed)

Prepare a bug-report bundle (one command)

When you open a bug, the maintainers will ask for a diagnostics bundle. Get it with:

margine-collect-diagnostics

That drops one .tar.gz in your home with logs, system state, kernel info, Flatpak inventory. Drag-and-drop it into the GitHub issue attachment.