{{Header}}
{{#seo:
|description=Troubleshooting Installation and Network Issues with {{project_name_long}}
|image=Troubleshooting-114197640.jpg
}}
[[File:Troubleshooting-114197640.jpg|thumb|Troubleshooting]]
<div class="mininav">
* [[#ISO|ISO]]
* [[#Connectivity Troubleshooting|Connectivity]]
* [[#General Troubleshooting|General Troubleshooting]]
</div>
{{intro|
The wiki page covers troubleshooting tips for installation issues, general issues, network issues and hardware problems.
}}
= ISO =
== ISO to USB Image Writer Tools ==
functional, bootable image:

* Flashing using a Qubes Kicksecure VM with hide hardware information enabled using <code>cp</code>
* Flashing using a Qubes Kicksecure VM using KDE ISO Image Writer from Flathub
* Flashing using a Debian VM balanaEtcher AppImage.
* Flashing using a Windows OS with balanaEtcher installer version.
* Flashing using a Windows OS with UNetbootin (portable).

broken:

* Flashing using a Qubes Kicksecure VM with [[Security-misc#Reduce_Kernel_Information_Leaks_|hide hardware information]] enabled using balanaEtcher, which shows an error message due to hide hardware information.

== Tips ==
* Exercise on separate notebook.
* Use a VM to flash for security against data loss.

== Live ISO Known Issues ==
=== KDE ISO Image Writer ===
{{quotation
|quote=The last block was not fully written (-1 of 1,048,576 bytes)!
|context=KDE ISO Image Writer Error Message
}}

{{ContentImage|
[[File:isoimagewritererror.png|400px|KDE ISO Image Writer Error Message]]
}}

<ref>
* Question: Why does it happen with {{project_name_short}} ISO but not with Debian or some other ISO?
** Answer: Not sure. Maybe a race condition. Or perhaps the premise might be wrong. A web search for this error message shows [https://askubuntu.com/questions/1471562/creating-a-windows-10-installation-usb-on-ubuntu-22-04 running Ubuntu and attempting to flash a Windows 10 ISO using KDE ISO Image Writer] failed. Also [https://www.reddit.com/r/kde/comments/zvoo0l/iso_image_writer_broken/ flashing KDE Neon failed]. This error seems to be reproducible with many Linux distributions. It is probably only possible for the KDE ISO Image Writer developers to fix this bug. There is probably nothing that the {{project_name_short}} ISO could do better.

KDE upstream bug report: [https://bugs.kde.org/show_bug.cgi?id=474195 "Last block was not fully written" error if usbstick is not unmounted, does not unmount on its own]
</ref>

In this case, try to unmount the USB device first or use a different ISO Image Writer tool.

=== DVD Support ===
[[File:Cd-rom-icon.png|50px|thumb]]

[[Untested]]. Should work in theory. Tested inside QEMU and VirtualBox with an emulated CD-ROM drive. So chances are good that it would work with a real DVD drive as well.

=== Dual Boot ===
It is recommended to physically disconnect any other physical disks while installing {{project_name_short}} (or any other operating system) to mitigate the risk of the installer overwriting the wrong drive due to user error or software bugs.

=== Fastboot ===
Fastboot is a BIOS setting which skips attempting to boot from USB on some computers. In this case, the user must disable Fastboot in order to be able to boot from USB.

=== Minor Issues ===
This might be an issue while installing additional packages while running the live ISO. This will not be an issue after installing to hard drive.

==== Failed to mount sysroot.mount - /sysroot. ====
Cosmetic issue only. Can be safely ignored.

Details here: https://forums.kicksecure.com/t/iso-error-message-during-boot-mount-sysroot-special-device-liveos-rootfs-does-not-exist/418

==== update-grub ====
Please report a bug if this breaks something for you. Adding a workaround for this would not be difficult.

<pre>
sudo update-grub 
</pre>

<pre>
/usr/sbin/grub-probe: error: failed to get canonical path of `LiveOS_rootfs'.
zsh: exit 1     sudo update-grub
</pre>

== Calamares ISO Installer ==
=== Language Selection ===
The Calamares installer by {{project_name_long}} by design does not ask for keyboard configuration, timezone or language during installation. It is recommended to configure that after the first boot after installation in case this is needed.

= Connectivity Troubleshooting =
== ICMP Fix ==

{{mbox
| image   = [[File:Ambox_notice.png|40px|alt=info]]
| text    = Note: Kicksecure firewall does not exist yet at time of writing.
}}

Therefore no such fix required yet.

== Qubes-specific Connectivity Issue ==
Complete the following steps:

# Shut down <code>{{project_name_gateway_vm}}</code>.
# Change the <code>{{project_name_gateway_vm}}</code> NetVM setting from <code>sys-firewall</code> to <code>sys-net</code>.
# Restart <code>{{project_name_gateway_vm}}</code>.

This procedure might help, but should not be considered a final solution. <ref>
This procedure was useful for [[Qubes|{{q_project_name_long}}]] R3.2 users, although the Qubes bug report is now resolved: https://github.com/QubesOS/qubes-issues/issues/2141
</ref>

== Why can't I Ping the {{project_name_gateway_long}}? ==

{{mbox
| image   = [[File:Ambox_notice.png|40px|alt=info]]
| text    = Note: Kicksecure firewall does not exist yet at time of writing.
}}

<s>The {{project_name_gateway_short}} does not respond to ping or similar commands because it is firewalled for security reasons; see ''{{W_Firewall}}'' or refer to the {{project_name_short}} source code. In most cases it is unnecessary to ping the {{project_name_gateway_short}} anyhow.

If you insist on pinging the {{project_name_gateway_short}} or have a unique setup that requires it, then this can be tested by clearing all firewall rules with the [https://github.com/{{project_name_short}}/developer-meta-files/blob/master/dangerous-scripts/dev_clearnet dev_clearnet] script. Alternatively, a script can be run to try and [[Dev/Firewall_Unload|unload / remove every iptables rule]], or the {{project_name_short}} firewall can be hacked to not load at all. The latter method is only for experts and it is necessary to comment out ''exit 0'' at the beginning.</s>

----

= General Troubleshooting =

== Introduction ==

Troubleshooting issues can be time intensive and success cannot be guaranteed. Some users expect {{project_name_short}} to provide an easy experience. While the {{project_name_short}} developers make every effort to meet user expectations, limited funding and human resources makes meeting these expectations impossible.

Even though problems emerge when using {{project_name_short}}, the cause is most often unrelated to {{project_name_short}} code. For example, users often report the same {{project_name_short}} release worked on different hardware and/or with a different host operating system. Most software such as the host operating system or the virtualizer is developed by independent entities; this is the norm in Linux distributions. See [[Linux User Experience versus Commercial Operating Systems]] to learn more about these relationships, as well as organizational and funding issues in the Open Source ecosystem.

== Essential General Troubleshooting Steps ==

{{mbox
| image   = [[File:Ambox_notice.png|40px|alt=info]]
| text    = The following recommended steps will fix many startup, freezing or other unusual issues in {{project_name_short}}. Skips steps that are no longer possible if a virtual machine is not bootable.
}}

{{box|text=
'''1.''' "Forget" about {{project_name_short}} for a moment and imagine you had never heard of the platform. Test your host computer first.

'''2.''' Exclude basic [[#Hardware Issues|hardware issues]].

'''3.''' Ensure the virtual machine (VM) images have been imported into a supported virtualizer listed on the [[Download]] page.

'''4.''' Debian (based) Linux host operating system users only: The following command should not show any errors. <ref name=lengthy_test>
This process can be lengthy.
</ref>

{{CodeSelect|code=
sudo dpkg-reconfigure -a
}}

'''5.''' Debian (based) Linux host operating system users only: The following command should be silent and not show any errors or output at all. <ref name=lengthy_test />

{{CodeSelect|code=
sudo dpkg --configure -a
}}

'''6.''' Debian (based) Linux host operating system users only: Next attempt to retrieve all available updates.

{{CodeSelect|code=
sudo apt update
}}

{{CodeSelect|code=
sudo apt full-upgrade
}}

'''7.''' Check for possible [[#Low RAM Issues|Low RAM Issues]].

* [[#Free up Additional Memory Resources|Free up Additional Memory Resources]].
* Also refer to [[RAM|Advice for Systems with Low RAM]].

'''8.''' Virtualizer-specific troubleshooting.

* [[VirtualBox/Troubleshooting|VirtualBox Troubleshooting]] / [[VirtualBox/Troubleshooting#General VirtualBox Troubleshooting Steps|General VirtualBox Troubleshooting Steps
]]
* [[KVM#Troubleshooting|KVM Troubleshooting]]

'''9.''' Check if other VMs are functional, such as newly created ones or those from a different vendor.

# "Forget" about {{project_name_short}} for a moment and imagine you had never heard of the platform. Test the virtualizer host software first.
# Try a VM other than {{project_name_short}} such as Debian <code>{{Stable project version based on Debian codename}}</code>.
# If the issue persists, this means the root issue is not caused by {{project_name_short}}, see: [[unspecific]] to {{project_name_short}}. In this case, attempt to resolve the issue as per [[Self_Support_First_Policy|Self Support First Policy]].

'''10.''' Check [[#System Logs|System Logs]].

* Sometimes crashing or freezing issues are easier to detect by [[#Watch Systemd Journal Log of Current Boot|Watching Systemd Journal Log of <u>Current</u> Boot]].
* Sometimes it is necessary to [[#Check Systemd Journal Log of Previous Boot|Check Systemd Journal Log of <u>Previous</u> Boot]].

'''11.''' If a graphical environment (where one can use a computer mouse) is unavailable after booting, utilize a virtual console to acquire system logs.

# [[Recovery#Virtual_Consoles|Recovery, Virtual Consoles]].
# Check system logs of the previous boot (step 10).

'''12.''' Use recovery mode to acquire system logs.

# Boot in [[Recovery#Recovery_Mode|recovery mode]].
# Check system logs of previous boot (step 10).

'''13.''' Use a chroot to acquire system logs.

If a virtual console is inaccessible and recovery mode is also broken, try [[Recovery#Chroot|using a chroot for recovery]].
}}

== Low RAM Issues ==

If insufficient RAM is available for {{project_name_short}} VM they might become unusable. Low RAM issues in {{project_name_short}} are commonly caused by:

* Unnecessary processes running and/or multi-tasking on the host OS.
* Multiple, open browser tabs.
* Unnecessary processes running in the {{project_name_short}} VM.
* Allocating more RAM to the {{project_name_short}} VM than is available; this prevents the VM from booting.
* Insufficient RAM allocated to the {{project_name_short}} VM.
* Other non-{{project_name_short}} VM running in parallel.

Insufficient RAM can cause multiple issues, but the most common effects include:

* Slow or unresponsive applications.
* The VM, mouse and/or keyboard freeze.
* Scrolling causes window staggers or jumps.
* Issues become worse when additional browser tabs or processes are spawned.
* Overall performance is poor.

See also: [[RAM|Advice for Systems with Low RAM]].

=== Free up Additional Memory Resources ===

If a VM needs additional memory, then free up resources and/or add more RAM to the VM:

* Terminate any non-essential processes on the host.
* Shut down any non-essential VM.
* Shut down and/or close non-essential processes and browser tabs in {{project_name_short}} VM.

To add additional RAM to the {{project_name_short}} VM, follow the platform-specific advice below.

=== KVM ===
{{KVM_RAM}}

=== {{q_project_name_short}} ===

Utilize Qube Manager: <br />
* <code>Qube Manager</code> &rarr; <code>VM_name</code> &rarr; <code>Qubes s<u>e</u>ttings</code> &rarr; <code>Advanced</code> &rarr; <code>Max memory:</code> <code><i>mem_size</i></code>

=== VirtualBox ===

# To add RAM in VirtualBox the VM <u>must</u> first be powered down.
# <code>Virtual machine</code> &rarr; <code>Menu</code> &rarr; <code>Settings</code> &rarr; <code><i>Adjust</i></code> <code>Memory slider</code> &rarr; <code><i>Hit:</i> OK</code>

See also: [[VirtualBox/Troubleshooting]].

= System Logs =
<ref>
"user support template": https://forums.whonix.org/t/workstation-keeps-freezing/7693/6
</ref>

== Check Systemd Journal Log of Current Boot ==
To inspect the systemd journal log of the current boot, run.

{{CodeSelect|code=
sudo journalctl -b
}}

This command requires pressing arrow keys like &uarr;, &darr;, &larr;, &rarr;, as well as <code>PgUp</code> and <code>PgDn</code> for scrolling.

For convenient reading of the log (until the command is issued), the log can be dumped to file. For example, the following command would write the log to file <code>~/systemd-log</code>.

{{CodeSelect|code=
sudo journalctl -b > ~/systemd-log
}}

Use any available editor to read the log file, such as <code>mousepad</code>.

{{CodeSelect|code=
mousepad ~/systemd-log
}}

== Watch Systemd Journal Log of Current Boot ==
It is possible to to watch the systemd journal log as it is written.

{{CodeSelect|code=
sudo journalctl -b -f
}}

== Check Systemd Journal Log of Previous Boot ==

It is possible to inspect the systemd journal log of the previous boot.

{{CodeSelect|code=
sudo journalctl -b -1
}}

This command requires pressing arrow keys like &uarr;, &darr;, &larr;, &rarr;, as well as <code>PgUp</code> and <code>PgDn</code> for scrolling.

For convenient reading of the log (until the command is issued), the log can be dumped to file. For example, the following command would write the log to file <code>~/systemd-log-previous</code>.

{{CodeSelect|code=
sudo journalctl -b -1 > ~/systemd-log-previous
}}

Use any available editor to read the log file, such as <code>mousepad</code>.

{{CodeSelect|code=
mousepad ~/systemd-log-previous
}}

== View List of Systemd Journal Logs ==
{{CodeSelect|code=
sudo journalctl --list-boots
}}

{{Anchor|Daemon Log}}

== Daemon Log View ==
To view the log of a specific systemd unit. Syntax:

(Replace <code>unit-name</code> with the actual name of the systemd unit.)

{{CodeSelect|code=
sudo journalctl -b --no-pager -u unit-name
}}

Example:

{{CodeSelect|code=
sudo journalctl -b --no-pager -u sdwdate
}}

== Daemon Log Follow ==
To follow the log of a specific systemd unit. Syntax:

(Replace <code>unit-name</code> with the actual name of the systemd unit.)

{{CodeSelect|code=
sudo journalctl -f -b --no-pager -u unit-name
}}

Example:

{{CodeSelect|code=
sudo journalctl -f -b --no-pager -u sdwdate
}}

== Daemon Status ==
To view the status of a specific systemd unit. Syntax:

(Replace <code>unit-name</code> with the actual name of the systemd unit.)

{{CodeSelect|code=
sudo systemctl status --no-pager unit-name
}}

Example:

{{CodeSelect|code=
sudo systemctl status --no-pager sdwdate
}}

== Check Systemd Journal Log of Failed Boot ==

An alternative to recovery mode might be [[Desktop#Virtual_Consoles|virtual consoles]], since they are an easier and more lightweight solution. A virtual console login might still be possible when the graphical user interface no longer starts.

Prerequisite knowledge: [[Desktop#Virtual Consoles|Virtual Consoles]]. Try to log in to a virtual console in a functional VM as an exercise. If that works, try a virtual console login in the broken VM.

If a virtual console is unavailable:

# Boot into [[Recovery|Recovery Mode]].
# Reboot into normal mode so a log for the failed boot will be written (if not previously enabled).
# Boot into recovery mode again.
# [[#Check_Systemd_Journal_Log_of_Previous_Boot|Check Systemd Journal Log of Previous Boot]].

= Permission Fix =

{{mbox
| image   = [[File:Ambox_notice.png|40px|alt=info]]
| text    = If something does not work, do not arbitrarily try to use sudo / root without any indication this is appropriate. Otherwise, this can negatively affect the correct user home folder permissions. See also: [[root|Safely Use Root Commands]].
}}

{{Open a product ws terminal}}

{{CodeSelect|code=
sudo chown --recursive user:user /home/user
}}

= Hardware Issues =

== General Recommendations ==

Rhetorical questions:

* When was the last time a qualified person disassembled your computer/notebook and removed dust from the fan and checked the cooling system of the CPU?
* How often should maintenance be performed?
* What is your CPU temperature under heavy system load?
* What is the room temperature where the computer is operating?

Recommendations:

* Ensure your computer or notebook has regular, proper maintenance.
* Monitor CPU temperature by utilizing relevant host operating system tools.
* Consider cooling the room where computers/notebooks operate.
* Better placement (more air space) around computers or notebooks can help.
* Consider a passive or active (notebook) cooling pad. <ref>Perform thorough research beforehand.</ref>
* [[#memtest86+|Run <code>memtest86+</code>]] to rule out RAM problems.

None of these issues are related to {{project_name_short}}. Therefore, please do not ask these questions in {{project_name_short}} support channels (until there is a {{project_name_short}} Host DVD available) as per [[Self_Support_First_Policy|Self Support First Policy]].

== memtest86+ ==

{{Box|text=
'''1.''' Install the <code>memtest86+</code> tool.

On Debian (based) hosts such as [[Kicksecure]].

{{Install Package|package=
memtest86+
}}

For other host operating systems, refer to <code>memtest86+</code> upstream documentation.

'''2.''' Reboot.

'''3.''' Start <code>memtest86+</code> from (grub) boot menu.

'''4.''' Keep <code>memtest86+</code> running for a significant period.

This should be run for as long as practically possible; for example, ideally overnight or for 8+ hours.

'''5.''' Check the <code>memtest86+</code> output.

If there are any issues, red error messages appear in the middle of the screen.

'''6.''' Done.

The memory test is complete.

If <code>memtest86+</code> identified any issues, these can manifest in various ways such as system crashes at random times. In such cases, the only likely solution is replacing the faulty hardware (RAM banks). <ref>RAM bank warranties may apply.</ref>
}}

== Hard Drive Health Check ==
TODO: document

also known as S.M.A.R.T

* smartmontools
* gsmartcontrol
* smart-notifier 
* nvme-cli
* package: gnome-disk-utility run: gnome-disks
* https://packages.debian.org/bookworm/lm-sensors
* https://packages.debian.org/bookworm/plasma-disks
* https://packages.debian.org/bookworm/psensor
* https://wiki.debian.org/SystemMonitoring

= See Also =

* [[RAM|Advice for Systems with Low RAM]]
* [[VirtualBox/Troubleshooting|VirtualBox Troubleshooting]]
* [[KVM#Troubleshooting|KVM Troubleshooting]]
* [[Recovery|Recovery Mode]]
* [[SysRq|System Recovery using SysRq Key]]
* [[Core Dumps]]

= Footnotes =
{{reflist|close=1}}

{{Footer}}

[[Category:Documentation]]