margine-os

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.

Start here: the System Check

Open Margine System and press Run next to System Check. It runs every validator Margine ships and tells you, one line per check, whether the system still matches how it left the build. A clean result means the problem is in an app or in your session, not in the OS: the rest of this page is the app-and-session checklist. (Same checks as ujust margine-doctor, if you prefer the terminal.)

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.

An external monitor on a USB-C dock stays black

You plug in a USB-C dock, the mouse and keyboard on it work, the network works, and the monitor stays dark. That is not GNOME and not the graphics driver: the laptop and the dock never agreed to carry video over the cable, so there is no signal for anything to find. Some laptops get this wrong now and then when the dock is plugged in after boot. The Framework 13 AMD does it most of the time.

Margine notices and fixes it on its own. About six seconds after you plug the dock in, if the dock reports that video was never set up, the USB-C controller is re-initialised and the monitor comes up. The only thing you will see is the dock's devices dropping and coming back for about a second. Nothing happens when the monitor is already working, or when the dock simply has no monitor attached.

If it did not happen, or you are on a machine Margine does not do this for automatically:

ujust margine-dock-wake

Same fix, by hand, on any machine and with any dock. To see what the automatic path decided, or to turn it off if it misbehaves with your dock:

ujust margine-dock-rescue status
ujust margine-dock-rescue off

The manual ujust margine-dock-wake keeps working with the automatic part off.

One thing this cannot help with: a laptop that will not boot while the dock is powered on. That happens before the operating system exists, and on the Framework 13 AMD it is a known firmware issue. Power the dock on after the login screen, or plug it in then.

The second monitor ignores the workspace keys, or the dock is on the wrong screen

Two monitors, and things are split in odd ways: the top bar on one screen and the dock on the other, or windows on the second screen that Super+1..5 and the move-to-workspace keys simply ignore, as if that screen were one fixed workspace. Three different settings, all in your own user profile, none of them hardware.

The second screen ignores the workspace keys. That one is a choice, not a fault, and Margine keeps GNOME's default: workspaces live on the primary display only, so a second monitor is one fixed workspace. Super+1..5 switch the primary, windows on the other screen stay where they are, and Super+Shift+Ctrl+arrows still move a window from one monitor to the other. If you would rather have every screen change together:

gsettings set org.gnome.mutter workspaces-only-on-primary false

and gsettings reset org.gnome.mutter workspaces-only-on-primary puts the fixed second screen back.

The dock sits on the laptop screen while the bar is on the external one. Dash to Dock remembers a specific connector once you have picked a monitor in its settings, and that memory wins over "follow the primary". Reset it and the dock follows the primary display again:

gsettings --schemadir /usr/share/gnome-shell/extensions/dash-to-dock@micxgx.gmail.com/schemas \
  reset org.gnome.shell.extensions.dash-to-dock preferred-monitor-by-connector

If you would rather have the dock on every screen, the extension's settings have a "Show on all monitors" switch.

More workspaces than the five Margine ships. If your machine ever ran with dynamic workspaces, GNOME kept rewriting the count in your profile and it can stay there, shadowing the image default. One reset puts it back to five:

gsettings reset org.gnome.desktop.wm.preferences num-workspaces

The phone webcam does not appear in apps

Start Phone Camera and press Start Camera before opening the app that needs the camera: the virtual device is invisible while nothing is streaming. If it is still missing, press Refresh in the app's Troubleshooting section (it restarts the desktop camera service) and reload the page or reopen the app. Full guide: Use your phone as a webcam.