3.4 Troubleshooting Installations

Troubleshooting Installations

Most Kali install failures fall into a handful of well-known buckets. The exam tests whether you can match a symptom to its cause, so learn these as symptom-to-fix pairs.

The machine will not boot the Kali media at all

• Secure Boot — the number-one cause on modern PCs. Secure Boot is a UEFI feature that only loads bootloaders signed with trusted keys, and Kali does not ship with Secure Boot support. The symptom is a firmware-level refusal: a message about a security policy violation, or the USB simply being skipped. The fix is to enter the UEFI/BIOS setup (usually via F2, F10, F12, Esc, or Del at power-on) and disable Secure Boot.
• UEFI versus legacy BIOS mismatch — if the USB stick does not appear in the boot menu, or boots in the wrong mode, look at the boot-mode settings. Modern systems default to UEFI; some also offer a legacy/Compatibility Support Module (CSM) mode. Pick the USB entry explicitly labeled UEFI and keep the install mode consistent — mixing a UEFI-booted installer with a legacy-boot target disk layout (or vice versa) produces a system that installs fine and then cannot boot.
• Corrupt media — a truncated download or a bad flash produces media that hangs immediately, drops to a bootloader error, or dies partway through the install with I/O errors. Before anything exotic, re-run the Section 3.1 procedure: verify the SHA256 checksum, then reflash with a reliable tool (balenaEtcher, Rufus in DD image mode, or dd on Linux/macOS). A surprisingly large share of broken installs is fixed right here.

The boot starts but hangs or shows nothing useful

When the system freezes behind a splash screen, make it talk. At the boot menu, highlight an entry and press Tab (or e, depending on the bootloader) to edit the kernel command line, then delete the quiet and splash parameters. You now get a verbose boot: kernel messages scroll past, and the hang point — a driver probe, a firmware request, a disk error — is visible instead of hidden behind a logo. On an installed system you can make this permanent by editing GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub and running update-grub.

Black screen or garbled display after boot

This is almost always a graphics driver problem, most notorious with certain NVIDIA and AMD cards. The kernel tries to set a native display mode (kernel modesetting) that the hardware or driver combination cannot handle. The fix is the nomodeset kernel parameter: edit the command line as above and append nomodeset, which forces a simple fallback display path so you can boot and then install the proper driver. Two shortcuts the exam likes:

1. Boot Live (fail-safe mode) from the menu — it bundles nomodeset with other conservative parameters, so it doubles as a quick test of whether graphics (or APIC/DMA) features are the culprit.
2. If the desktop dies but the machine is alive, switch to a text console with Ctrl+Alt+F2 and work from there.

A black screen is a display failure, not a failed install — resist the urge to reinstall before trying nomodeset.

Reading the logs

• dmesg prints the kernel ring buffer: device detection, driver errors, firmware loading failures, USB problems. Pipe it through grep for what you suspect, e.g. dmesg | grep -i firmware or dmesg | grep -i error.
• journalctl -b shows the current boot's full systemd journal; journalctl -p err filters to errors.
• During installation, the Debian installer keeps its log at /var/log/syslog (and switches to a shell console with Alt+F2/Alt+F3, log view with Alt+F4). After the install finishes, the installer log is preserved under /var/log/installer/ — the first place to look when a specific step, such as partitioning or package installation, failed.

Resource and media pitfalls

Kali's stated minimums are tiered — as little as 128 MB of RAM (512 MB recommended) and 2 GB of disk for a headless, SSH-only box, but at least 2 GB of RAM and 20 GB of disk for the default Xfce desktop with the kali-linux-default toolset — and falling under them produces ugly, nondescript failures: the graphical installer freezing midway, the out-of-memory killer terminating processes, or package configuration failing for lack of space. On a memory-starved machine, use the text-mode installer (the plain Install menu entry) instead of Graphical install, and consider a lighter desktop than Xfce or a minimal install. In VMs, also check that you allocated enough video memory and enabled the right firmware type (UEFI versus BIOS) in the hypervisor settings to match the media you created.

A diagnostic order that works

1. Verify checksum, reflash media.
2. Disable Secure Boot; confirm UEFI mode and the correct boot entry.
3. Boot verbose (strip quiet/splash) and read where it stops.
4. Black screen? Add nomodeset or use fail-safe mode.
5. Still stuck? Read dmesg, journalctl, and /var/log/installer for the actual error.

Following that sequence resolves the overwhelming majority of failed installs without guesswork.

Less obvious culprits worth knowing

A few failures look mysterious until you have seen them once. Some machines refuse to boot from USB 3.x ports under certain firmware — moving the stick to a USB 2.0 port (or recreating it with a different flashing tool) gets past a bootloader that loads and immediately dies. If the installer fails specifically at the Select and install software or mirror-configuration step, suspect the network path rather than the media: a blocked or outdated mirror breaks package retrieval, and pointing the installer at the main kali-rolling archive (or installing offline from the full ISO) works around it. Finally, a machine that boots the installer but cannot see its own disk is often running storage in RAID/Intel RST mode in firmware; switching the SATA mode to AHCI in the UEFI setup makes the disk visible to the kernel — a fix you will meet again whenever Kali shares a disk with Windows.