Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Troubleshooting Methodology

This page is the spine of the troubleshooting section. It gives you an ordered way to work a problem on InterGenOS, from the cheapest checks to a full recovery, and tells you when to escalate and how to ask for help so that someone can actually act on it.

The approach mirrors how InterGenOS itself is built: surface every error, never mask one, and turn an unverified assumption into a checked fact before you act on it. Security is not first. It is only. The goal of every step below is the same goal as the system: a machine you understand, can modify, and can trust.

InterGenOS is version 1.0-dev (build id v1.0-dev1). The shipped desktop is GNOME 49 on Wayland. Where a command, package name, or flag is specific to a subsystem, this page points you to the focused page for that subsystem rather than guessing.

The escalation ladder

Work a problem in order. Most issues resolve at the first or second rung; the later rungs exist so that a hard problem still has a defined path and you never have to improvise under pressure.

  1. Basic — observe, reproduce, and read the obvious signals.
  2. Advanced — read logs, isolate the failing component, change one variable at a time.
  3. Recovery — restore a known-good state when the running system can no longer be trusted.
  4. Support — gather evidence and escalate so someone can act on facts, not guesses.

Do not skip rungs. A “fix” applied before you have reproduced the problem is a guess, and a guess that appears to work hides the real cause until it resurfaces later.

Rung 1 — Basic

Start here for every problem. The aim is to state the problem precisely and gather the cheapest signals before touching anything.

  • State the symptom exactly. What did you do, what did you expect, what happened instead? “It is broken” is not a symptom; “the login screen appears, I enter my password, and it returns to the login screen” is.
  • Reproduce it. A problem you cannot reproduce is a problem you cannot confirm you have fixed. Note the exact steps. If it only happens sometimes, note how often and under what conditions (cold boot vs. warm reboot, on battery vs. plugged in, after a specific action).
  • Read the obvious signals first. On-screen error text, a failed action, a missing icon. Read the message literally before interpreting it.
  • Confirm scope. Does it affect one application, one user account, or the whole system? One app misbehaving and the whole desktop failing are different problems with different first steps.
  • Note what changed. Did the problem start after an update, a new package, a settings change, or a hardware change? The most recent change is the first suspect.

If the problem is specific to one area, jump to the focused page once you have the symptom in hand:

The FAQ covers common first-time questions and may resolve the issue before you go further.

Rung 2 — Advanced

If the basic signals do not resolve it, move to evidence. The principle here is the same one the build process uses: read the logs end to end, do not spot-check, and change one variable at a time. An “it works now” after changing three things at once tells you nothing about which change mattered.

  • Read the system and session logs. The journal carries the real story — failed units, service errors, and the boot sequence. A success banner on screen is not a passing grade; the failures that matter hide in the logs. Review the current boot with journalctl -b.
  • Check for failed units. A service that failed to start, or one locked down so tightly it cannot write its own state, is a common and silent cause. List failed units with systemctl --failed, then read the status and recent log lines for each.
  • Isolate the failing component. Narrow from “the system” to a single service, package, device, or configuration file. Reproduce against that component alone where you can.
  • Change one variable, then re-test. Revert it if it does not help. Keep a written list of what you changed so you can undo cleanly and so a fix is attributable to a single change.
  • Distinguish a by-design failure from a real one. Some subprocesses are expected to fail and are handled; do not chase those. Confirm whether a failing line is genuinely the cause before acting on it.
  • Verify, do not assume. Trace the behavior to its source. If you cannot support a conclusion with a log line or a reproduced result, it is a hypothesis, not a finding.

For the kinds of failures tied to building or installing packages, and for the host-side validation gates that catch most misconfigurations early, see Package & Build Failures.

InterGenOS ships local assistance that can help you read and interpret this evidence offline. InterGen is a tiered, hardware-detected, offline-first local assistant (built on Qwen models) with zero telemetry; it can help explain a log line or a failed unit without anything leaving the machine. InterGen Sentinel is a pluggable security scanner whose default backends are Local-Rules and a Local-Qwen model. See the Assistant section for how to use them.

Rung 3 — Recovery

Move to recovery when the running system can no longer be trusted to give honest answers, or cannot boot far enough to investigate: a broken boot chain, a graphical session that will not start, a configuration change that locked you out, or a corrupted component.

InterGenOS is built to make recovery a defined operation rather than an improvisation, because the system carries the trust machinery that recovery depends on:

  • A signed Secure Boot chain. A Microsoft-signed shim validates GRUB, which verifies the kernel’s signed UKI; on an installed system the UKI is MOK-signed and regenerated on every kernel install, so a tampered kernel cannot boot under your enrolled key.
  • Image integrity. The read-only live ISO image is sealed with dm-verity — its root hash carried inside the signed UKI — so the installer/live environment is verified before it runs. On the installed system, pkm verify confirms every installed file against its signed SHA-256, so “are my files intact?” is a question with a checkable answer, not a guess.

Practical recovery paths:

  • Boot a known-good target. If a recent change broke boot, recovering to a previously working boot entry or the installation media is the fastest way back to a usable system to investigate from.
  • Reinstall cleanly when in doubt. Because the system is built from source and reproducible, and the installer (Forge) writes a verifiable system, a clean reinstall is a legitimate and honest recovery step, not a defeat. See the Forge install guide and the Recovery & Reinstall page for the supported flow, including the encrypted-disk and broken-boot-chain paths.
  • Use the package manager (pkm) to restore packages from the signed mirror. The mirror’s index is signed as a whole and verified against one signature, so a restore comes from a source whose integrity you can check yourself.

Do not “fix” a recovery by hand-editing the running system and declaring it done. A change that only holds because of a manual edit on a running box is a note about a fix, not a fix; it must be re-applied through a supported path and survive a clean boot to be trusted. If the change belongs in the system itself, see Service & Hardware Issues for where service and hardware configuration lives.

Rung 4 — Support (Phone-A-Friend)

If the problem outlasts the first three rungs, escalate. The goal of this rung is to make your problem actionable for someone else: a clear symptom, a reproduction, and the evidence you gathered.

Bring with you:

  • The exact symptom and the steps to reproduce it.
  • What changed most recently (update, package, setting, hardware).
  • The relevant log excerpts and failed-unit output from Rung 2 — the actual lines, not a paraphrase.
  • The InterGenOS version and build id (v1.0-dev1), and whether the issue is on the live ISO, after install, or after an update.
  • What you have already tried, and the result of each attempt.

A vague report (“it does not work”) cannot be acted on; an evidence-backed report often resolves on the first reply.

Phone-A-Friend (Frontier/Cloud Escalation)

For problems where local analysis is not enough, InterGen Sentinel supports Phone-A-Friend (Frontier/Cloud Escalation): a set of opt-in cloud providers you can choose to route a question to. This is off by default and never sends anything until you opt in for a specific check. The supported providers are Claude (Anthropic), Gemini (Google), Copilot (Microsoft), ChatGPT (OpenAI), Grok (xAI), and DeepSeek. The local backends (Local-Rules and Local-Qwen) remain the default; cloud escalation is a deliberate, per-use choice that you control.

This keeps the same posture as the rest of the system: nothing leaves the machine unless you decide it should, and you can see and check what is being sent.

See also