On this page
Start with the command output and the profile or package source that owns the failing component. Avoid deleting package databases, using broad overwrite options, or retrying disk operations until you know which target is affected.
Package update fails
OnixOS uses full upgrades. Use either the project helper or pacman directly:
opkg update
sudo pacman -SyuDo not run pacman -Sy and then install an unrelated package. That leaves installed packages on a partial upgrade. If a transaction fails, keep the complete error and resolve the reported package or repository problem before retrying.
A repository database cannot be downloaded
Check the active repository names and URLs in /etc/pacman.conf, then open the repository index to see whether the expected path is available. The three-entry example on the repository guide uses HTTP and SigLevel = Never; profile build configurations use HTTPS and also include a firmware repository. Use the configuration intended for the machine you are setting up.
If the repository exists but its package does not, check its architecture and whether that package source is in the configured build list. A source project is not a published package until the repository build has produced it.
Installer does not start
Confirm that you booted the intended profile and that the image filename matches the release and architecture. Core starts the Onix CLI installer; desktop and Security profiles use Calamares; Server starts its own profile-local installer. archinstall is included as a fallback.
Core’s current CLI installer requires UEFI/GPT. The Server installer supports BIOS and UEFI. For the desktop graphical installer, start from a desktop profile that includes Calamares. See the installation guide and the individual profile pages.
Disk or partition selection is unclear
Stop before confirming any operation that erases or repartitions a disk. Record the device names from the live environment and identify the intended target by size and model. Back up data first. The Server installer has a final disk-erasure confirmation; do not proceed unless the selected disk is correct.
Desktop configuration looks wrong
Run the read-only diagnostics, then review the configuration before changing it:
onix-configure --diagnose
onix-configure --show-configThe installed onix-configure(8) manual describes supported options. The helper only applies desktop profiles for components it detects as installed.
Find the source of a defect
Use the package inventory to find the package source, and the profile reference to find the image configuration. For source-level issues, use the OnixOS GitLab group or the community forum. Include the profile, architecture, package name and complete error text in a report; omit passwords, tokens and private system data.