Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
79 lines (49 loc) · 3.37 KB

TROUBLESHOOTING.md

File metadata and controls

79 lines (49 loc) · 3.37 KB
Raw

Troubleshooting

The USB does not appear in the UEFI boot list

  • Reopen the builder log in your Windows Downloads directory and confirm the final verification succeeded.
  • Insert the USB before powering on the target computer.
  • Select the entry prefixed with UEFI, not a legacy or CSM entry.
  • Disable Secure Boot. The builder intentionally launches Debian's GRUB binary directly.
  • Try a firmware boot menu instead of changing the permanent boot order.

MOK manager is missing

Secure Boot is still affecting the boot path, or the firmware is launching the wrong EFI entry. Disable Secure Boot and choose the UEFI USB entry again. This project does not enroll a Machine Owner Key.

The menu opens but pressing Y returns an error

The target guard refused the internal disk. Read AUTO_HOOK.log or AUTO_INSTALL_FAILURE.log from the USB on another computer. Each examined disk is logged with its Linux device name, model, removable flag, byte size, and device path.

Rebuild the USB with a model substring that appears exactly in that log and a narrow size range that includes the logged decimal byte size. The builder parameters use decimal GB: one GB is 1,000,000,000 bytes.

Never broaden the guard until multiple disks could match.

The installation stopped in the Debian installer

Restart the computer and boot the USB again. If an earlier run reached disk authorization, the menu displays a guarded retry choice. Press Y to start a fresh attempt; prior USB logs are cleared after the safety checks pass.

Use R at the GRUB menu to restart without touching a disk.

INSTALL ALREADY COMPLETE appears

The USB recorded a successful installation and removed its customized initrd so it cannot be reused accidentally. Run the Windows builder again to deliberately create a newly armed installer.

The installed computer says no boot device

  • Remove the installer USB.
  • Keep firmware boot mode set to UEFI.
  • Put the internal drive's Debian/UEFI entry ahead of legacy entries.
  • Do not switch to legacy/CSM mode after a UEFI installation.

If the internal disk is visible in firmware but no Debian entry exists, boot official Debian rescue media and repair GRUB. Include AUTO_PARTMAN.log and the target machine's firmware model when reporting a reproducible problem.

Console login says Login incorrect

Use the administrator username configured with -AdminUser and the console password saved by the builder under Windows Downloads. Password characters are not displayed while typing.

Root login is disabled. After logging in as the administrator, use:

sudo -i

SSH does not connect

Confirm the target has Ethernet and received a DHCP address. Try:

ssh admin@debian-node.local

Replace both values with your configured username and hostname. If multicast DNS is unavailable on the client network, connect to the target's IP address instead.

SSH password authentication is intentionally disabled. Use the private key corresponding to the public key supplied to the builder:

ssh -i ~/.ssh/id_ed25519 admin@192.0.2.10

Reporting a problem

Include:

  • Windows and PowerShell versions
  • USB size and model
  • Target computer and disk models
  • The builder log
  • Relevant USB installer logs
  • The exact screen or error message

Remove public keys, IP/MAC addresses, serial numbers, hostnames, and other identifying values before posting logs publicly.