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

This section is for when something does not behave as expected, whether you are running InterGenOS on hardware or building it from source. InterGenOS is a built-from-source, security-only-aligned distribution: the goal is a machine you understand, can modify, and can trust, so the troubleshooting guidance here favors understanding the root cause over applying an opaque workaround.

InterGenOS is currently at version 1.0-dev (build id v1.0-dev1). Pages in this section will continue to grow as the system stabilizes and more commands and flows are documented.

How to use this section

Start with the methodology page if you are not sure where a problem belongs. It covers the general approach: read the actual error, identify which layer it comes from (boot, desktop, a service, a package build), and gather the facts before changing anything. From there, jump to the page that matches your symptom.

  • Troubleshooting methodology — a general approach to diagnosis: read the error, locate the layer, gather facts, change one thing at a time.
  • Boot and graphical issues — the system does not boot, drops to a console, or the graphical session fails to start. The shipping desktop today is GNOME 49 on Wayland.
  • Service and hardware issues — a system service will not start, or a hardware device is not detected or behaves incorrectly.
  • Package and build failures — problems installing or building software, including the from-source build pipeline.

Build-pipeline gates (for builders)

If you build InterGenOS from source, the build runs through 20 phases, beginning with a fast validate phase that checks reproducibility and correctness before any compilation starts. A failure here is cheap to fix: it halts before the build chroot is created, so you can correct the finding and relaunch without reverting any state.

The detailed walkthrough of those gates — audit coverage, tier validation, build-order and dependency scans, and how to resolve each correctly rather than silence it — belongs with the build-side material. The package and build failures page is the entry point for build problems in this wiki.

Before you ask for help

Two habits make a problem far easier to diagnose, for you and for anyone helping:

  1. Quote the exact error. Copy the real message, not a paraphrase. The precise text, including any package names, paths, or exit codes, is usually the fastest route to the cause.
  2. Change one thing at a time. When you apply a fix, change a single variable and re-test, so you know what actually resolved the issue.

If your question is more “how does this work” than “this is broken,” the FAQ is the better starting point. For security configuration and verified-boot questions, see the security section and the install section. Security here is not first. It is only — so when a fix would weaken the system’s integrity, treat that as a reason to find a different fix, not to accept the weaker one.

  • Start here — orientation and the FAQ.
  • Installation — Forge, the installer, and recovery.
  • Security — the verified-boot chain, hardening, and trust boundaries.