Troubleshooting

This guide covers common issues you might encounter when building or running SerenityOS.

Building SerenityOS

CMake is Outdated

Error: CMake version too old

Problem: CMake fails to configure the build.Solution: Ensure CMake version is >= 3.16:

cmake --version

If your system doesn’t provide a suitable version, download a binary release from the CMake website.

QEMU is Missing or Outdated

Error: QEMU version too old

Problem: QEMU is not found or version is too old.Solution: Ensure QEMU version is >= 5:

qemu-system-i386 -version

Install QEMU from your package manager or build it:

Toolchain/BuildQemu.sh

Toolchain is Outdated

Error: Compiler version mismatch

Problem: You see an error like:

CMake Error at CMakeLists.txt:28 (message):
  GNU version (13.1.0) does not match expected compiler version (13.2.0).

  Please rebuild the GNU Toolchain

Or:

Your toolchain has an old version of binutils installed.
    installed version: "GNU ld (GNU Binutils) 2.40"
    expected version:  "GNU ld (GNU Binutils) 2.41"
Please run Meta/serenity.sh rebuild-toolchain x86_64 to update it.

Solution: Rebuild the toolchain:

Meta/serenity.sh rebuild-toolchain x86_64

If CMake still shows errors after rebuilding, start with a fresh build:

Meta/serenity.sh rebuild x86_64

The toolchain is updated every few months to use the latest compilers and build tools. When an update is due, the build will fail with a clear error message.

GCC is Missing or Outdated

Error: GCC version too old

Problem: Your system GCC is too old.Solution: Ensure GCC version is >= 14:

gcc --version

If your GCC binary has a different name, specify it when running CMake:

cmake ../.. -GNinja \
  -DCMAKE_C_COMPILER=gcc-14 \
  -DCMAKE_CXX_COMPILER=g++-14

Legacy Renegotiation Disabled

SSL/TLS connection issues

Problem: SSL/TLS connections fail during build.Solution: Ensure /etc/ssl/openssl.cnf has the following options:

[openssl_init]
ssl_conf = ssl_sect

[ssl_sect]
system_default = system_default_sect

[system_default_sect]
MinProtocol = TLSv1.2
CipherString = DEFAULT@SECLEVEL=1
Options = UnsafeLegacyRenegotiation

Build Problems After git pull

Build broken after update

Problem: Build fails after pulling latest changes.Solution:

Rebuild the toolchain:

Meta/serenity.sh rebuild-toolchain x86_64

If that doesn’t help, try with a clean repo:
```
Meta/serenity.sh rebuild x86_64
```
If still broken, ask in the #build-problems channel on Discord.

If it builds on CI, it should build for you too. A clean rebuild usually fixes the issue.

Running SerenityOS

The VM is Really Slow

Poor VM performance

Problem: QEMU runs very slowly.Solution:Linux: Ensure KVM is available:

ls -l /dev/kvm

The run script automatically enables KVM if /dev/kvm exists and is readable/writable by your user.Windows: Enable WHPX (Windows Hypervisor Platform) acceleration in Windows Features.

Slow Boot on HiDPI Systems

Slow boot on Windows with >100% scaling

Problem: Boot phase crawls on Windows with display scaling >100%.Solution:The default display backend (SERENITY_QEMU_DISPLAY_BACKEND=sdl,gl=off) does not have this problem. If you’re affected:

Open properties of C:\Program Files\qemu\qemu-system-x86_64.exe
Go to Compatibility tab
Change DPI settings to force scaling by the System
Adjust the setting at the bottom of the window

The QEMU window will render at normal size with acceptable emulation speeds.

This is tracked as issue #7657.

Boot Failures

Error: Kernel Image too big for memory slot

Problem: Boot fails with “Error: Kernel Image too big for memory slot. Halting!”Solution:This means the kernel has grown too large. This is a known issue that requires attention:

Contact the team on Discord server
Open a GitHub issue
Try reverting recent changes to see if that helps temporarily

Error: Computer does not support long mode

Problem: “Your computer does not support long mode (64-bit mode). Halting!”Solution:

Bare metal: Your machine doesn’t support x86_64 extensions
VirtualBox: Enable x64 virtualization mode in VM settings
QEMU: Don’t use qemu-system-i386, which doesn’t support x86_64. Use qemu-system-x86_64 instead.

Error: Computer does not support PAE

Problem: “Your computer does not support PAE. Halting!”Solution:

Bare metal: Your CPU is too old to boot SerenityOS
VirtualBox: Enable PAE/NX in VM settings
QEMU: The CPU model configuration is not exposing PAE. Check QEMU CPU models

Error: KVM doesn't support guest debugging

Problem: Boot fails with KVM debugging error.Solution:

Update host kernel to at least version 5.10 (required for KVM_CAP_SET_GUEST_DEBUG)
Ensure your distro has QEMU debug features enabled

Or disable KVM debugging:

SERENITY_DISABLE_GDB_SOCKET=1 ninja run

Frequently Asked Questions

Will SerenityOS support X?

Maybe. Maybe not. There is no plan. If you want to see something happen, you can implement it yourself!

Where are the ISO images?

There are no ISO images. SerenityOS does not cater to non-technical users.

To run SerenityOS, you need to build it from source. See the Build Instructions.

Does SerenityOS have a package manager?

Package management in SerenityOS

Short answer: No, SerenityOS does not have a “Linux-style” package manager.Why not?

SerenityOS uses a monorepo approach - all software is built together
The ABI (library symbols, syscall interfaces) has no stability guarantee
The ABI can change at any moment
POSIX C library API remains relatively stable
No need for binary packages when everything is built from source

What about third-party software?Use Ports in the Ports/ directory:

Ports are third-party software that runs on SerenityOS
Each port comes with an install script
Ports are always built from source
Currently, ports should be cross-compiled on the host
Compiling ports on SerenityOS itself is possible but not recommended yet

Future plans:The pkg tool may improve this workflow in the future. Join #package-manager on Discord if you want to contribute.Excluding components:You can exclude SerenityOS components at compile time. See Advanced Build Instructions.

Why implement X instead of using library Y?

The SerenityOS project maximizes hackability, accountability, and fun by implementing everything ourselves.

Getting Help

If you can’t find a solution here:

Ask in #build-problems on Discord
Search existing GitHub issues
Open a new issue with details about your problem

Setup

Debugging & Profiling

Virtualization

Building SerenityOS

CMake is Outdated

QEMU is Missing or Outdated

Toolchain is Outdated

GCC is Missing or Outdated

Legacy Renegotiation Disabled

Build Problems After git pull

Running SerenityOS

The VM is Really Slow

Slow Boot on HiDPI Systems

Boot Failures

Frequently Asked Questions

Will SerenityOS support X?

Where are the ISO images?

Does SerenityOS have a package manager?

Why implement X instead of using library Y?

Getting Help

See Also

Build docs developers (and LLMs) love

Setup

Debugging & Profiling

Virtualization

​Building SerenityOS

​CMake is Outdated

​QEMU is Missing or Outdated

​Toolchain is Outdated

​GCC is Missing or Outdated

​Legacy Renegotiation Disabled

​Build Problems After git pull

​Running SerenityOS

​The VM is Really Slow

​Slow Boot on HiDPI Systems

​Boot Failures

​Frequently Asked Questions

​Will SerenityOS support X?

​Where are the ISO images?

​Does SerenityOS have a package manager?

​Why implement X instead of using library Y?

​Getting Help

​See Also

Build docs developers (and LLMs) love

Building SerenityOS

CMake is Outdated

QEMU is Missing or Outdated

Toolchain is Outdated

GCC is Missing or Outdated

Legacy Renegotiation Disabled

Build Problems After git pull

Running SerenityOS

The VM is Really Slow

Slow Boot on HiDPI Systems

Boot Failures

Frequently Asked Questions

Will SerenityOS support X?

Where are the ISO images?

Does SerenityOS have a package manager?

Why implement X instead of using library Y?

Getting Help

See Also