Troubleshooting

Almost every Keru failure lands in exactly one of five stages: live boot, network, fetch, build, or finalize. Figure out which, and you're most of the way to a fix.

Live boot

Symptom	Cause / fix
Drops to an emergency shell	live/init couldn't find the installer payload or mount buffers. Check the ISO layout and that you wrote the whole image, not just the files.
Installer never auto-starts	The live init runs installer/install.sh on boot. Run it by hand from the shell to see its errors directly.
Nothing on screen	Terminal TTY not your display? Verify the kernel picks your console; a plain getty on tty1 is the default.

Network

• Installer says offline. It probes a few hosts (1.1.1.1, github.com, the project mirror) and loops: it will offer to run nmtui, then re-check. Let it.
• DHCP won't bite. Use nmtui and set a static address. The installer doesn't care how the link comes up, only that it does.
• Slow fetch. When SOURCE_MIRROR is set it's tried first; upstream is the fallback. A broken mirror yields timeouts — fix or unset SOURCE_MIRROR.

Fetch

• 404 on a download. The recipe's url missed a version bump. Fix it or report it — sources are pinned in kama-packages.
• Checksum mismatch. The tarball in the cache doesn't match the recipe. Clear the cache dir for that package: rm -rf /var/cache/kama/dl/<pkg>.
• Mirror poison. If a third-party mirror serves a tampered file, fetch fails verification and refuses to proceed — by design.

Build

Symptom	Cause / fix
Compile error in a package	Often a C(FLAGS) interaction or a missing build dep. Add the dep and re-run kama make — stage dirs cache progress.
Missing header	That's a temp-dep gap in the recipe's deps=(). Contribute the fix: one line in kama-packages.
Toolchain failure	Stage 0 is the sharpest edge. A failing binutils/gcc/libc bootstrap is a bug — file it with the full make.conf combo.
Kernel build dies with no reason	Free disk or memory on the build host first; kernel builds are hungry. Then check KERNEL_CONFIG in make.conf.

Finalize and first boot

• mkfs fails. The target device is in use or the filesystem tools for your pick are missing. Unmount and retry.
• Won't boot. The init you chose must agree with how your bootloader was told to run it — check the boot command line and your init's expectations.
• No network after boot. Your network tool choice (nmtui alone won't auto-connect) needs to be started on default runlevel or its service enabled.
• Unstable combo. Keru warns on unproven pairs (musl+systemd, uclibc-ng, zfs root ...). Heed the warning or expect rough edges. It never blocks you.

← Getting started · Security model →