Troubleshooting

pulsar doctor checks the machine; pulsar report packages the results for someone else. Neither needs root.

Start with doctor

Plain pulsar runs it too. Each check prints ok, warn or FAIL, with detail where useful. On the NVIDIA image:

Only FAIL exits 1. Warnings don’t mean broken. Checks that don’t apply are silent.

What each check reads

Check	What it tells you
`scheduler`	Whether the sched_ext scheduler actually attached, read from /sys, not from systemd. A kernel that cannot load one is fine: stock EEVDF.
`ntsync`	Whether /dev/ntsync is there for Proton.
`gamemode`	Whether you are in the gamemode group, and whether this session already knows it.
`mangohud`	Whether the MangoHud Flatpak layer is on the same runtime branch Steam runs on.
`greenboot`	Whether this boot passed its health checks. A red boot is a fail: greenboot is counting down to a rollback.
`nvidia`	NVIDIA image only. The module is loaded and matches the driver the image expects. An NVIDIA GPU with no module is a fail.
`flatpak-gl`	NVIDIA image only. Every running Flatpak app (Steam, mostly) has the GL extension for the running driver.
`gpu-containers`	NVIDIA image only. A CDI spec exists for the running driver, and SELinux lets containers open the GPU.
`flathub`	Flathub is configured and unfiltered.
`fedora`	Fedora’s Flatpak remote is there, for the stock GNOME apps.
`origin`	This system follows a tag, not one frozen digest. A digest never updates, so that is a fail.
`updates`	Whether an update is staged, and how many packages you have layered.
`disk`	Free space on /sysroot. Warns at 80% full, fails at 90%: staging an update needs several GB.
`crashes`	Programs of yours that crashed since this boot.
`cli`	That `pulsar` on your PATH is this system’s CLI and not the Pulsar code editor, which ships a command with the same name.

Common findings

Most common:

Check	It says	Do this
`flatpak-gl`	Steam started without the NVIDIA … driver	Quit Steam fully (not just its window) and open it again. Until then its games get the iGPU and can show a black window.
`flatpak-gl`	Flatpak GL driver for nvidia … is missing	sudo systemctl start pulsar-gl-nvidia.service
`origin`	this system follows one image digest	Run the fix it prints: sudo rpm-ostree rebase <image>:latest
`gamemode`	… is not in the gamemode group	sudo pulsar setup gamemode, then log out and back in
`gamemode`	… enrolled in gamemode, but this session predates it	Log out and back in. Groups are fixed at login.
`nvidia`	nvidia variant but no nvidia module is loaded	Usually Secure Boot refusing a module it does not trust: enroll the key (see Install).
`gpu-containers`	stale CDI spec for driver …	Delete the hand-written spec it names in /etc/cdi. The boot unit writes the right one to /var/run/cdi.
`cli`	another pulsar comes first on PATH	Call /usr/bin/pulsar, or rename the editor’s command.

NVIDIA key enrollment · Rolling back

Asking for help

Paste pulsar report into an issue, forum post or agent. It includes doctor, deployments, the image manifest, failed units, this boot’s warnings from Pulsar’s units and the failed ones, GPUs and their drivers, and Flatpak remotes and apps. JSON by default; --text for people.

Left out: the full journal, earlier boots, environment variables, the machine ID, file contents from $HOME or /etc, Flatpak app data.

Redacted (best effort; read it before posting): hostname, username, home path (as ~), MAC and IPv4 addresses, email addresses, values after token=, password: or Authorization: Bearer, and prefixed tokens: GitHub (ghp_, github_pat_), GitLab (glpat-), sk- keys, Slack, AWS access keys, JWTs.

Reading the system journal needs the wheel, adm or systemd-journal group; otherwise the report says so in a note.

Crashes

systemd-coredump records every crash. With a default coding agent (the only one installed, or set with pulsar agent default), a crash shows a notification (once per program per boot) with an Ask button, which names your agent, and Ignore this, which stops announcing that program’s crashes. Nothing is sent unless you click Ask. Without one, pulsar doctor still lists crashes.

A crash report adds the program, signal, package, unit, command line, the crashing thread’s stack trace, and its log lines. Never the core file. Command lines can hold unrecognized secrets: check --text first. What Ask sends.

The logs

System units: pulsar-flatpaks (first-boot apps), pulsar-gamemode-group, pulsar-update-auto.timer, pulsar-update-stage, scx, greenboot-healthcheck; on NVIDIA also pulsar-gl-nvidia, pulsar-akmods-cert, nvidia-cdi-refresh, pulsar-gpu-containers.
Session units (journalctl --user -u <unit>): pulsar-update-check.timer, pulsar-gl-check.path, pulsar-crash-watch.path, pulsar-theme-init, gamescale-reconcile.

Checks are functions in cli/pulsar.

Written with help from AI and reviewed by a person before publishing. Spotted a mistake? Let us know.