# shadps4-emu Common Build Issues and Solutions: A Complete Troubleshooting Guide

> Troubleshoot common shadps4-emu build issues with this guide. Resolve missing dependencies, compiler errors, and Git submodule problems for successful compilation. Ensure Clang 18+ and Vulkan SDK.

- Repository: [shadps4-emu/shadPS4](https://github.com/shadps4-emu/shadPS4)
- Tags: how-to-guide
- Published: 2026-03-19

---

**Most shadPS4 build failures stem from missing system dependencies, outdated Clang compilers, or uninitialized Git submodules, all of which can be resolved by following the platform-specific documentation and ensuring Clang 18+ is used with the Vulkan SDK on your PATH.**

The **shadps4-emu/shadPS4** repository is a modern PlayStation 4 emulator written in C++23 that relies on CMake and numerous third-party libraries. Due to its complex dependency chain—including Boost, Vulkan, FFmpeg, and SDL3—developers frequently encounter build-time errors that fall into predictable categories. This guide addresses the most common shadps4-emu build issues with specific fixes derived from the source code and official documentation.

## Missing Dependencies and CMake Configuration Errors

### Boost, VulkanHeaders, and SDL3 Detection Failures

CMake frequently aborts with `Could NOT find <Package>` errors when required libraries are not installed or visible. Common missing packages include **Boost**, **VulkanHeaders**, **SDL3**, and **FFmpeg**.

On Ubuntu and Debian-based systems, install the full dependency set before configuring:

```bash
sudo apt install build-essential clang cmake libasound2-dev libpulse-dev libopenal-dev libssl-dev zlib1g-dev libedit-dev libudev-dev libevdev-dev libsdl2-dev libjack-dev libsndio-dev libvulkan-dev vulkan-validationlayers libpng-dev

```

For the complete Linux dependency list, refer to [[`documents/building-linux.md`](https://github.com/shadps4-emu/shadPS4/blob/main/documents/building-linux.md)](https://github.com/shadps4-emu/shadPS4/blob/main/documents/building-linux.md).

## Git Submodule Initialization Errors

### aerolib.cpp and External Library Path Errors

If you see errors such as `src/core/aerolib/aerolib.cpp: No such file or directory`, the repository's Git submodules have not been initialized. The shadPS4 project includes external libraries as submodules that must be fetched separately.

Clone recursively from the start:

```bash
git clone --recursive https://github.com/shadps4-emu/shadPS4

```

Or, if you already cloned shallowly, initialize the submodules manually:

```bash
git submodule update --init --recursive

```

This instruction is documented in the **Cloning** section of [[`README.md`](https://github.com/shadps4-emu/shadPS4/blob/main/README.md)](https://github.com/shadps4-emu/shadPS4/blob/main/README.md).

## Compiler Version and C++23 Compatibility Issues

### Clang 18+ Requirement and Configuration

shadPS4 requires **Clang 18+** (or Clang 19 on Windows) because it uses C++23 features not available in older compilers. If CMake warns that "Clang 18 is the recommended compiler" or the build fails with C++23 syntax errors, you must explicitly set the compiler:

```bash
cmake -S . -B build \
      -DCMAKE_C_COMPILER=clang \
      -DCMAKE_CXX_COMPILER=clang++

```

The compiler recommendation appears at the top of [[`documents/building-linux.md`](https://github.com/shadps4-emu/shadPS4/blob/main/documents/building-linux.md)](https://github.com/shadps4-emu/shadPS4/blob/main/documents/building-linux.md).

### PIE (Position-Independent Executable) Warnings

On some Linux distributions, CMake may print `WARNING: PIE is not supported at link time`. This occurs when the toolchain lacks Position-Independent Executable support.

Use a recent Clang or GCC that supports PIE, or add the flags manually:

```bash
cmake -S . -B build -DCMAKE_POSITION_INDEPENDENT_CODE=ON

```

The PIE detection logic resides in [[`CMakeLists.txt`](https://github.com/shadps4-emu/shadPS4/blob/main/CMakeLists.txt) lines 22–31](https://github.com/shadps4-emu/shadPS4/blob/main/CMakeLists.txt#L22).

## Platform-Specific Build Failures

### Windows: MSYS2 Toolchain Limitations

The shadPS4 project explicitly warns that **"Building with MSYS2 is broken"** due to missing LLVM/Clang flags in the current MSYS2 toolchain. Do not use MSYS2/MinGW for building.

Instead, use **Visual Studio 2022** (Option 1) or **VSCode + Build Tools** (Option 2) as documented in [[`documents/building-windows.md`](https://github.com/shadps4-emu/shadPS4/blob/main/documents/building-windows.md) lines 5–9](https://github.com/shadps4-emu/shadPS4/blob/main/documents/building-windows.md#option-3-msys2mingw).

### Linux: Vulkan SDK and Driver Compatibility

Build failures in `src/video_core/renderer_vulkan/*` with "Vulkan headers not found" indicate the **Vulkan SDK** is missing or its `bin` directory is not on `PATH`.

Install the SDK from [vulkan.lunarg.com](https://vulkan.lunarg.com/) and verify installation:

```bash
vulkaninfo

```

Ensure `spirv-cross` and `glslc` remain accessible in `PATH`, as noted in [[`documents/patching-shader.md`](https://github.com/shadps4-emu/shadPS4/blob/main/documents/patching-shader.md)](https://github.com/shadps4-emu/shadPS4/blob/main/documents/patching-shader.md).

### SDL3 vs SDL2 Mismatch on Input Handling

Errors in `src/input/*` regarding missing [`SDL.h`](https://github.com/shadps4-emu/shadPS4/blob/main/SDL.h) typically result from installing the wrong SDL development package. The Windows build defaults to **SDL3**, while Linux may use **SDL2** on older distributions.

Install the correct package for your platform:

- Debian 12+ or Ubuntu 24.04+: `libsdl3-dev`
- Older distros: `libsdl2-dev`

CMake selects the target via `find_package(SDL3 CONFIG)` in [[`CMakeLists.txt`](https://github.com/shadps4-emu/shadPS4/blob/main/CMakeLists.txt) lines 233–236](https://github.com/shadps4-emu/shadPS4/blob/main/CMakeLists.txt#L233).

## Optimizing Build Configuration

### Disabling Optional Features for Faster Debug Builds

To reduce compile times during development, disable non-essential features such as Discord RPC and the auto-updater:

```bash
cmake -S . -B build \
      -DENABLE_DISCORD_RPC=OFF \
      -DENABLE_UPDATER=OFF \
      -DCMAKE_BUILD_TYPE=Debug

```

### Specifying Boost Versions Manually

When multiple Boost versions exist on your system, force CMake to use a specific installation:

```bash
cmake -S . -B build \
      -DBOOST_ROOT=/opt/boost_1_84_0 \
      -DCMAKE_PREFIX_PATH=/opt/boost_1_84_0

```

## Summary

- **Missing dependencies** are the most common cause of CMake failures; install the full package list from `documents/building-<os>.md` before configuring.
- **Uninitialized submodules** cause "file not found" errors for [`src/core/aerolib/aerolib.cpp`](https://github.com/shadps4-emu/shadPS4/blob/main/src/core/aerolib/aerolib.cpp); always clone with `--recursive` or run `git submodule update --init --recursive`.
- **Compiler version** matters: shadPS4 requires **Clang 18+** for C++23 support; set `CMAKE_C_COMPILER` and `CMAKE_CXX_COMPILER` explicitly if CMake selects the wrong toolchain.
- **Platform-specific pitfalls** include broken MSYS2 support on Windows, missing Vulkan SDK paths on Linux, and SDL3/SDL2 mismatches in `src/input/*`.
- **Build optimization** flags like `-DENABLE_DISCORD_RPC=OFF` and manual Boost root specifications can significantly speed up development cycles.

## Frequently Asked Questions

### Why does CMake fail to find Boost even after I installed it?

CMake relies on `find_package(Boost)` to locate headers and libraries. If Boost is installed in a non-standard directory or if the version is too old, CMake cannot detect it. Resolve this by installing the development packages (`libboost-all-dev` on Ubuntu) or explicitly pointing CMake to the installation with `-DBOOST_ROOT=/path/to/boost`.

### Can I build shadPS4 with GCC instead of Clang?

While GCC might compile the project, **shadPS4 officially requires Clang 18+** (or Clang 19 on Windows) because it utilizes C++23 features and LLVM-specific optimizations that are not fully supported in older GCC releases. For the most stable build experience, always use the recommended Clang version specified in [`documents/building-linux.md`](https://github.com/shadps4-emu/shadPS4/blob/main/documents/building-linux.md).

### How do I fix "aerolib.cpp: No such file or directory" errors?

This error indicates that Git submodules containing external libraries were not fetched during the clone. Run `git submodule update --init --recursive` from the repository root to download the missing dependencies. In the future, use `git clone --recursive https://github.com/shadps4-emu/shadPS4` to ensure all submodules are present from the start.

### What is the minimum Vulkan version required for shadPS4?

shadPS4 requires **Vulkan 1.3** with specific format feature flags supported by your GPU driver. If you encounter runtime warnings about "missing format feature flags" or build errors in `src/video_core/renderer_vulkan/*`, ensure you have installed the latest Vulkan SDK from LunarG and that your GPU drivers are up to date. Verify installation by running `vulkaninfo` from your terminal.