Skip to content

Troubleshooting

Jump to bottom
jw edited this page Jul 27, 2026 · 1 revision

Troubleshooting

This page covers common ModernGekko-Template setup, build, recompilation, and runtime problems all in one shot. Let's go

Before reporting an issue, update the repository and initialize every submodule:

git pull --recurse-submodules
git submodule sync --recursive
git submodule update --init --recursive

Then run the environment check:

make check

For the experimental LLVM backend:

make check BACKEND=llvm

Windows

Use MSYS2 UCRT64

Do not run the Makefile from Command Prompt or PowerShell. Run it EXCLUSIVELY in UCRT64.

Install MSYS2 from PowerShell if necessary:

winget install -e --id MSYS2.MSYS2

Open MSYS2 UCRT64 from the Start menu and update it:

pacman -Syu

MSYS2 may ask you to close the terminal. Reopen MSYS2 UCRT64, run pacman -Syu again, then install the required tools:

pacman -S --needed \
    base-devel git \
    mingw-w64-ucrt-x86_64-toolchain \
    mingw-w64-ucrt-x86_64-cmake \
    mingw-w64-ucrt-x86_64-ninja

Verify the environment:

echo "$MSYSTEM"
which gcc
which g++
which cmake
which ninja
which make
which sh
gcc -dumpmachine

Expected results include:

UCRT64
/ucrt64/bin/gcc
/ucrt64/bin/g++
x86_64-w64-mingw32

The syntax of the command is incorrect

This usually means make was launched from Command Prompt or PowerShell.

Open MSYS2 UCRT64, return to the template directory, and retry:

make tools

Submodule setup failed and now gets skipped

Remove the stale setup stamp:

rm -f .git/.recomp-submodules-stamp

Then retry:

git submodule update --init --recursive
make tools

CMake reports an unsupported platform with 4-byte pointers

Example:

You're building on an unsupported platform: 'AMD64' with 4-byte pointers.

CMake selected the wrong compiler or reused an incompatible build cache from another shell.

Verify that UCRT64 GCC is active:

which gcc
gcc -dumpmachine

Then remove the cached tool builds:

rm -rf lib/DolRecomp/build
rm -rf lib/ModernGekko/build
make tools

Do not reuse build directories after switching between MSVC, MinGW, UCRT64, Clang, or GCC.

CMake generator mismatch

Example:

generator: Ninja
Does not match the generator used previously: Visual Studio 17 2022

Delete the affected build directories:

rm -rf lib/DolRecomp/build
rm -rf lib/ModernGekko/build
make tools

ModernGekko-Template uses Ninja. Do not configure the same build directory with both Ninja and Visual Studio generators.

Errors inside qos2.h

Examples include:

QOS_FLOWID has not been declared
QOS_NON_ADAPTIVE_FLOW was not declared

This commonly occurs when a non-MSYS2 Windows compiler, such as Scoop's GCC distribution, is selected.

Check every GCC installation visible through PATH:

type -a gcc
type -a g++

The first results should be:

/ucrt64/bin/gcc
/ucrt64/bin/g++

Temporarily correct PATH if necessary:

export PATH=/ucrt64/bin:/usr/bin:$PATH
hash -r

Then remove the old build directories and rebuild:

rm -rf lib/DolRecomp/build
rm -rf lib/ModernGekko/build
make tools

Linux

CMake cannot find a dependency

Install the dependency packages listed on the Getting Started page, then check that pkg-config can locate them:

pkg-config --version
pkg-config --list-all | grep -E 'evdev|udev|gtk|alsa|pulse'

After installing missing packages, remove the cached build directory and retry:

rm -rf lib/ModernGekko/build
make tools

Build process is killed

If the terminal prints Killed, the kernel probably terminated a compiler process because the system ran out of memory.

Reduce build parallelism:

make tools JOBS=2

For a game module:

make recompile GAME=Game-Slug JOBS=2

For LLVM:

make llvm GAME=Game-Slug JOBS=2

Close memory-heavy applications before using the LLVM backend. LLVM object generation may require significantly more memory than the default C backend did.

On older template revisions, JOBS=2 may limit the CMake build without limiting every LLVM object worker. Update to the latest template if LLVM still launches too many workers.

Submodules

A submodule directory is empty

Run:

git submodule sync --recursive
git submodule update --init --recursive

Confirm their state:

git submodule status --recursive

A line beginning with - means that submodule has not been initialized.

Tool builds

dolrecomp or moderngekko-port is missing

Build both tools:

make tools

Build them separately if isolating a failure:

make dolrecomp
make moderngekko

Game extraction and selection

ISO= or GAME= is required

The first operation for a game must provide the ISO:

make run ISO="/path/to/game.iso"

The filename is converted into a game slug under extracted/.

After extraction, use that slug without providing the ISO again:

make run GAME=Game-Slug

See the available extracted games:

ls extracted

ISO path contains spaces

Quote it:

make run ISO="/home/user/Games/My Game.iso"

Experimental LLVM backend

CMake cannot find LLVM

DolRecomp currently expects LLVM 19 or 20.

Check the installed version:

llvm-config --version

Provide LLVM's CMake directory explicitly:

make llvm GAME=Game-Slug \
    LLVM_DIR="$(llvm-config --cmakedir)"

You can also provide the directory manually:

make llvm GAME=Game-Slug \
    LLVM_DIR="/path/to/llvm/lib/cmake/llvm"

LLVM object generation was interrupted

Do not delete the generated output directory.

Resume generation with:

DOLRECOMP_LLVM_RESUME=1 make llvm GAME=Game-Slug

On Windows, finished module caching works normally. Some older revisions may fail to reuse individual LLVM COFF object files and rebuild those chunks. Update to the latest template if resume does not recognize existing Windows objects.

InstCombine did not reach a fixpoint

Update the template and its pinned submodules first:

git pull --recurse-submodules
git submodule sync --recursive
git submodule update --init --recursive

Then rebuild the LLVM-enabled tools:

rm -rf lib/DolRecomp/build
rm -rf lib/ModernGekko/build
make tools BACKEND=llvm

If the error remains, report the complete LLVM message and the guest function or chunk address shown immediately before the failure.

Do not delete the existing LLVM object output if you intend to resume it.

Runtime problems

Game opens to a black window

First test without graphics:

make run GAME=Game-Slug \
    RUN_ARGS="--headless --allow-interpreter"

If headless mode continues farther, test Vulkan explicitly:

make run GAME=Game-Slug \
    RUN_ARGS="--graphics Vulkan --allow-interpreter"

This helps separate CPU or recompilation problems from graphics configuration problems.

Reset the ModernGekko configuration

On Linux:

mv ~/.local/share/moderngekko \
   ~/.local/share/moderngekko.backup

On Windows from UCRT64:

mv "$LOCALAPPDATA/moderngekko" \
   "$LOCALAPPDATA/moderngekko.backup"

Restart ModernGekko after renaming the directory. The old configuration remains available in the backup directory.

Compare the C and LLVM backends

Run the default C backend:

make run GAME=Game-Slug BACKEND=c \
    RUN_ARGS="--headless --allow-interpreter"

Run the LLVM backend:

make llvm-run GAME=Game-Slug \
    RUN_ARGS="--headless --allow-interpreter"

If one backend works and the other does not, include that difference in the bug report.

Possible self-modifying code warning

DolRecomp may report a possible self-modifying or executable-memory patching instruction.

This is a warning, not necessarily an immediate failure. Test with:

make run GAME=Game-Slug \
    RUN_ARGS="--allow-interpreter"

Include the reported guest address when opening an issue.

Cleaning builds

Remove compiled tools while preserving extracted games:

make clean-tools

Remove generated modules and extracted games:

make clean-extracted

Remove everything generated by the template:

make clean

For a toolchain or CMake cache problem, prefer removing only the tool builds:

rm -rf lib/DolRecomp/build
rm -rf lib/ModernGekko/build

Do not run a full clean before attempting to resume a long LLVM build.

Reporting an issue

Include all of the following:

git rev-parse HEAD
git submodule status --recursive
make check

Also include:

  • Operating system and version
  • Linux distribution, or Windows shell environment
  • CPU architecture
  • Compiler and version
  • CMake and Ninja versions
  • Exact command that failed
  • Full output beginning at the first error
  • Selected backend, c or llvm
  • Selected toolchain
  • Whether the failure happens in headless mode
  • Whether --allow-interpreter changes the result
  • Whether the C and LLVM backends behave differently in testing

Useful version commands:

gcc --version
clang --version
cmake --version
ninja --version
make --version
llvm-config --version

On Windows, also include:

echo "$MSYSTEM"
which gcc
which cmake
which ninja

Do not attach any copyrighted game assets whatsoever.

Clone this wiki locally