Maze Linux / Wiki

Diagnostics

Three commands answer nearly every "what is wrong with my machine" question.

maze-doctor

A full health report of the system — 18 sections. This is the first thing to run when anything misbehaves, and the output to attach when reporting a bug.

sudo maze-doctor

A healthy system reports 0 failures.

The Stability section

This section answers the question people actually have: "was that Maze's fault, or my hardware?"

If your machine froze or shut itself down, maze-doctor shows the last line the kernel wrote before the previous boot ended, and classifies the cause:

• hardware — a USB device that vanished, a disk that stopped answering, overheating
• out of memory
• graphics driver
• kernel fault

When the evidence is not conclusive it says inconclusive rather than guessing. That is deliberate: a confident wrong answer sends you looking in the wrong place for hours.

maze-boot-check

Verifies the boot chain end to end, covering the kernel image, its signature, and encrypted-disk unlocking.

It runs automatically after every update, and warns you before you shut down if something is wrong. You can also run it by hand:

sudo maze-boot-check
sudo maze-boot-check --repair    # fix what it finds

maze-boot-entries

If you have installed Maze more than once, dead entries can pile up in the firmware boot menu. This tool clears them out:

sudo maze-boot-entries           # show only
sudo maze-boot-entries --clean   # clean up (asks for confirmation)

It never touches entries belonging to other operating systems, nor the entry you are currently booted from.

Reporting a problem

Attach the output of:

sudo maze-doctor > report.txt

It answers almost every follow-up question on its own.

See also: If the System Won't Boot · Hardware Kill Switches

---

Useful flags

maze-doctor --deep        # longer, more thorough run
maze-doctor --no-color    # plain output, good for pasting into a report
maze-boot-check --quiet   # exit code only
maze-boot-check --no-flag # check without writing the unsafe-boot flag

If the boot check fails

maze-boot-check writes /var/lib/maze/boot-unsafe, and maze-boot-guard then holds a shutdown inhibitor — your machine will refuse to power off cleanly while the boot chain looks broken.

This is intentional: it stops you rebooting into a system that will not come back. Fix the boot chain (usually sudo maze-sb-sign) or see Won't Boot?, then shut down normally.