Troubleshooting

Troubleshooting

1. Rootfs configuration and APT

1.1 The rootfs YAML is rejected

Check the required keys and value types in YAML configuration syntax → Rootfs document. The repository list must be under buildinfo.distrorepo, and either base or packages must contain package names.

1.2 APT cannot update or authenticate a repository

Check that the repository URL, suite, architecture, and components are reachable and correct. Confirm that exactly one signing-key source is configured and that the key matches the repository metadata. A local keyring path is resolved from the rootfs YAML file's directory.

1.3 A package has no install candidate

Confirm that the package is present in the configured suite and components for the selected architecture. Check for misspellings and conflicts with the exclude list.

1.4 APT requires an excluded package

The build stops when the baseline or a requested package depends on an excluded package. Inspect the dependency chain and either remove the conflicting exclusion or choose a package set that does not require it.

2. Build environment

2.1 A build fails in a container

Check that the container permits the required mount, chroot, and device operations. If a previous run left mounts under the rootfs, unmount the reported paths in the same mount namespace before retrying. Package scripts that require /proc, /sys, or functional device nodes may still fail; see Limitations.

2.2 The APT worker cannot import Python-APT

Factory tries /usr/bin/python3 if its own interpreter cannot import Python-APT. Install the system package for that interpreter and verify the import with /usr/bin/python3 -c 'import apt, apt_pkg'.

2.3 A compressor or ISO tool is missing

Install the compressor selected in the rootfs YAML. For ISO builds, run the host dependency stage from the supplied asset directory, or install the required host tools before setting prepare_host to false. LZ4 compression levels require support in the installed mksquashfs.

3. ISO input and stages

3.1 Rootfs checksum verification fails

For a remote rootfs, check that the configured SHA-256 is correct or that the checksum sidecar is reachable and contains a valid digest. Local rootfs checksums are optional.

3.2 An ISO asset or stage cannot be found

Confirm that iso.data_dir points to the required asset tree and each iso.stages entry names an existing stage file. If prepare_host is enabled, the asset tree must also include 00-install-host-packages. See YAML configuration syntax → ISO document.