60 lines
2.3 KiB
Markdown
60 lines
2.3 KiB
Markdown
# Troubleshooting
|
|
|
|
## binfmt_misc (cross-arch builds)
|
|
|
|
When building ARM images on an x86_64 host, Linux uses `binfmt_misc` to run ARM binaries via QEMU. If you see:
|
|
|
|
```
|
|
update-binfmts: warning: Couldn't load the binfmt_misc module.
|
|
chroot: failed to run command '/bin/true': Exec format error
|
|
```
|
|
|
|
Fix:
|
|
|
|
```bash
|
|
sudo modprobe binfmt_misc
|
|
sudo apt-get install qemu-user-static binfmt-support
|
|
sudo update-binfmts --enable
|
|
```
|
|
|
|
On WSL2 you may need to install `binfmt-support` on the host Windows side or use Docker instead.
|
|
|
|
## "Required dependencies not installed"
|
|
|
|
The `depends` file lists tools that must be present on the build host. Read the README for the current install commands.
|
|
|
|
Note: `grub-efi-amd64-bin` and `grub-pc-bin` are data packages with no associated binary — they are not checked by the dependency checker but must be installed for `grub-mkrescue` to work.
|
|
|
|
## ISO doesn't boot
|
|
|
|
- Verify the ISO was written correctly: use Balena Etcher or `dd` — do not just copy the file.
|
|
- In VMware/VirtualBox, set firmware to UEFI.
|
|
- If GRUB appears but the system hangs after selecting a menu entry, try the "safe mode" entry (adds `nomodeset`).
|
|
|
|
## Squashfs / initramfs errors during export-iso
|
|
|
|
- `mkinitramfs: failed to determine device for /` — This happens when `MODULES=dep` is set in a chroot. The build sets `MODULES=most` to avoid this.
|
|
- `W: Couldn't identify type of root file system` — Expected during initramfs generation in a live build; the fstab is rewritten for live-boot and has no real block devices to detect.
|
|
|
|
## Stage fails despite SKIP file
|
|
|
|
`SKIP` files only skip re-running the stage scripts. They do not skip the export pipeline. Use `SKIP_IMAGES` to skip exports while still running the stage.
|
|
|
|
## Build fails on NTFS / exFAT partition
|
|
|
|
The work directory must be on a Linux filesystem (ext4, btrfs, xfs). NTFS and exFAT do not support the required file attributes. Set `WORK_DIR` to a path on a Linux filesystem:
|
|
|
|
```bash
|
|
export WORK_DIR=/mnt/linux-disk/vesperos-work
|
|
```
|
|
|
|
## Apt errors: "doesn't support architecture"
|
|
|
|
The VesperOS apt repo (`cdn.oxmc.me/apt`) currently only supports `arm64`/`armhf`. On amd64 builds you will see:
|
|
|
|
```
|
|
Notice: Skipping ... doesn't support architecture 'amd64'
|
|
```
|
|
|
|
This is expected and not an error — standard Debian repos are used for amd64 packages.
|