Lyra OSDocumentation

How-to guides

Troubleshooting

Investigate boot, network and update failures and prepare a useful report for the project.

DiagnosticsDesktop and Server · Lyra OS 1.1Documentation review: Translated from the Portuguese version reviewed on

The media does not boot

  1. Check the ISO checksum as described in the installation guide.
  2. Confirm that the image was written to the USB drive and that the firmware is booting from the correct UEFI entry.
  3. In a VM, check UEFI, memory and that the ISO is attached to the optical drive.
  4. Record the message shown, the machine model and the Secure Boot state.

No network connection

Check the cable or the Wi-Fi connection in the settings. On the Server, confirm that the network provides DHCP. To look up the interface addresses:

ip -brief address

If there is an address but the repositories do not respond, note whether the error mentions DNS, connection or certificate. Also check the system date and time. This information helps distinguish network failures from an unavailable repository.

An update failed

Wait for other package operations to finish and try again. Do not delete lock files or force the package manager to quit. Copy the error message and the name of the repository involved.

Read the guidance on package sources before accepting a new key, removing repositories or changing the base.

Gather system information

To identify the version, the kernel and failed services, run:

cat /etc/os-release
uname -r
systemctl --failed

If your image includes lyra-report, run it as a regular user:

lyra-report

The tool shows the collected data for review before creating a local file and does not upload anything automatically. If the command is not available, use the basic information above; you do not need to install development components to report a failure.

Report a reproducible problem

Open an issue in the corresponding repository: Desktop, Server or Vega. Search for a similar report first.

Include the information below:

Lyra OS edition and version:
ISO name, if the failure happened during installation:
Computer model or VM configuration:
UEFI and Secure Boot state:
Steps to reproduce:
Expected result:
Observed result and error message:

Review screenshots and logs before publishing. Remove passwords, tokens, keys and personal data, even when the tool applies anonymization. Share only the files needed to explain the problem.

Reference: diagnostics with lyra-report.