Skip to content

Troubleshooting

This page collects the failures people are most likely to meet, by the message they see. It starts from what Get Started has already run into and will grow from reports. If your problem is not here, Ask for help says what to gather and how to open a report, step by step. The issue tracker is the place to say so: it has forms for a bug or build problem, a question, and an engine request, and CONTRIBUTING.md says how a request is weighed. A security vulnerability is reported privately, as SECURITY.md describes.

Downloading and extracting the starter project

Section titled “Downloading and extracting the starter project”

curl: (22) The requested URL returned error: 404

Section titled “curl: (22) The requested URL returned error: 404”

There is no file at the address in the curl line of Get the starter project. Check that the whole line was pasted, as it is one long line, and run the box again. If it still fails, download the ZIP with your browser instead, as the same step says, from the release page it links.

tar cannot find the ZIP you named. The prompt must be in the folder that holds it, C:\dev on these pages, and the name must match exactly. dir /b *.zip lists the ZIP files in the current folder. A ZIP your browser saved is in your Downloads folder until you move it.

A different tar ran, not the one that comes with Windows. Git for Windows can add its own Unix tools to the command prompt, and their tar does not read ZIP files. This line makes the window look in Windows’ own folder of programs first, so that tar is Windows’ own until you close the window:

Terminal window
set "PATH=%SystemRoot%\System32;%PATH%"

It prints nothing. Then run the box that failed again, in the same window.

The project is in a folder named after the ZIP

Section titled “The project is in a folder named after the ZIP”

Extract All in File Explorer suggests a new folder named after the ZIP, such as C:\dev\labrador-starter-v0.3.0, and the ZIP’s own mygame folder goes inside it. A project in a long path fails to build (Choose a short folder), so move it to C:\dev\mygame. This box does that whether you extracted it beside the ZIP in C:\dev or in your Downloads folder, then removes the folder named after the ZIP if it is left empty, and lists the project’s files:

Terminal window
for /d %d in ("%USERPROFILE%\Downloads\labrador-starter-*" C:\dev\labrador-starter-*) do if exist "%d\mygame" move "%d\mygame" C:\dev\
for /d %d in ("%USERPROFILE%\Downloads\labrador-starter-*" C:\dev\labrador-starter-*) do rmdir "%d"
dir /b C:\dev\mygame

The prompt shows each command as it runs it. move prints 1 dir(s) moved., and the list ends with vcpkg.json, as in step 3 of Get the starter project. If move says Access is denied. or A duplicate file name exists, or the file cannot be found., C:\dev\mygame is there already: see step 1 of that page.

Not an error. vcpkg, which fetches the engine’s libraries when you configure, reads its list of package versions with Git. When Git is not installed it says this, downloads a private copy of Git of about 60 MB, and carries on. You do not need to install Git for the starter project.

Windows limits a path to 260 characters unless long paths are enabled, and a few files in the repository have long paths. Delete the partial clone and clone again into a short folder such as C:\dev. Enabling long paths with git config --global core.longpaths true lets the clone finish, but not the build that follows it, because the compiler keeps the 260-character limit even when long paths are enabled in Windows (Choose a short folder).

Every command in Get Started runs in the x64 Native Tools Command Prompt, which Install the tools says how to open. Other windows look much the same and fail in the ways below. To check the one you are in, run:

Terminal window
echo %VSCMD_ARG_TGT_ARCH%

The right prompt prints x64. Any other answer, including %VSCMD_ARG_TGT_ARCH% printed back, means the wrong prompt: close it, open the x64 Native Tools Command Prompt, go back to your folder with cd /d and the folder’s path, such as cd /d C:\dev\Labrador, and run the command again.

'cmake' is not recognized as an internal or external command

Section titled “'cmake' is not recognized as an internal or external command”

An ordinary Command Prompt prints this, followed by operable program or batch file., for cmake, cl, ninja or fxc. It has none of Visual Studio’s tools on its path.

The term 'cmake' is not recognized as the name of a cmdlet, function, script file, or operable program

Section titled “The term 'cmake' is not recognized as the name of a cmdlet, function, script file, or operable program”

The same mistake in a PowerShell or Terminal window, which also has none of the tools. The commands in these pages are written for the command prompt, so open the x64 Native Tools Command Prompt rather than looking for a PowerShell equivalent.

A 32-bit prompt: x86-windows, Hostx86 or warning C4309

Section titled “A 32-bit prompt: x86-windows, Hostx86 or warning C4309”

The plain Developer Command Prompt, Developer PowerShell and the x86 prompts set up the 32-bit compiler, and nothing refuses it at first. cmake --preset x64-debug configures without an error, but its output says vcpkg is Detecting compiler hash for triplet x86-windows... and names a compiler under Hostx86/x86/cl.exe, and vcpkg builds 32-bit copies of every dependency. Building Labrador itself then stops in the tests, after the samples have been built:

C:\dev\Labrador\tests\app\window_tests.cpp(477): error C2220: the following warning is treated as an error
C:\dev\Labrador\tests\app\window_tests.cpp(477): warning C4309: 'argument': truncation of constant value

Your own project builds no engine tests, so it may build a 32-bit game with no error at all. Either way the build folder is now a 32-bit one. Open the x64 Native Tools Command Prompt, check it prints x64 as above, then delete the build folder and configure again from your project’s folder:

Terminal window
rmdir /s /q out\build\x64-debug
cmake --preset x64-debug
cmake --build --preset x64-debug

'git' is not recognized, or INFO: Could not find "git".

Section titled “'git' is not recognized, or INFO: Could not find "git".”

Git for Windows is not installed, or was installed after this command prompt was opened, and a prompt does not see programs installed after it started. Only the Git route and Put your project in Git run git; the starter project does not need it. Install it as in Install the tools if you have not, then close the prompt and open a new x64 Native Tools Command Prompt.

git commit stops with this the first time on a machine:

Author identity unknown
*** Please tell me who you are.

and ends fatal: unable to auto-detect email address. Git needs a name and an email address to put in the commit. Set them as in Tell Git who you are, with your own name and address in place of the examples, then run the same git commit line again.

git -C external/labrador checkout v0.2.0 in Start your own project prints this. It is not an error: the engine’s folder is on one fixed release rather than a branch, which is what a pinned engine should be. Nothing needs undoing, and the note’s advice about git switch does not apply.

external/labrador is empty, or does not contain a CMakeLists.txt file

Section titled “external/labrador is empty, or does not contain a CMakeLists.txt file”

Configuring a project whose engine folder is empty stops with:

CMake Error at CMakeLists.txt:11 (add_subdirectory):
The source directory
C:/dev/mygame/external/labrador
does not contain a CMakeLists.txt file.

The project was cloned without --recurse-submodules, so Git made the submodule’s folder but did not fill it. From the project’s folder, fill it in, then configure again:

Terminal window
git submodule update --init --recursive
cmake --preset x64-debug

The first line prints Submodule path 'external/labrador': checked out and the commit it checked out. Clone with git clone --recurse-submodules next time, and the engine comes with the project.

Could not read presets from C:/dev and File not found: C:/dev/CMakePresets.json

Section titled “Could not read presets from C:/dev and File not found: C:/dev/CMakePresets.json”
Output
CMake Error: Could not read presets from C:/dev:
File not found: C:/dev/CMakePresets.json

The prompt is not in your project’s folder. A new prompt starts in your user folder or wherever it last was, and cmake --preset, cmake --build --preset and ctest --preset all look for CMakePresets.json in the folder the prompt is in, so each prints these two lines, with that folder in place of C:/dev, and does nothing. Starting the game from the wrong folder prints The system cannot find the path specified. Nothing was changed. Go to the project’s folder and run the command again:

Terminal window
cd /d C:\dev\mygame

The prompt then ends C:\dev\mygame>. The same message naming C:/dev/mygame/game means the prompt is one folder too deep, in game; the cd line above fixes that too. For the engine’s own build, the folder is C:\dev\Labrador, or C:\dev\mygame\external\labrador as Run the samples shows.

Could not find toolchain file: "/scripts/buildsystems/vcpkg.cmake"

Section titled “Could not find toolchain file: "/scripts/buildsystems/vcpkg.cmake"”

VCPKG_ROOT is not set, so the path to vcpkg’s toolchain starts with nothing. The errors about Ninja and the compiler that follow are consequences of this one. Check first that the window is the x64 Native Tools Command Prompt, which sets it when Visual Studio’s vcpkg component is installed (the wrong command prompt). If it is, follow If VCPKG_ROOT is not set. Then delete the half-configured build folder and configure again:

Terminal window
rmdir /s /q out\build\x64-debug
cmake --preset x64-debug

In Visual Studio rather than the prompt, the fix is the same setx line in that section, followed by closing and reopening Visual Studio.

Configure stops with this when it cannot find fxc.exe, the Windows SDK’s shader compiler, which the Direct3D 11 and Direct3D 12 renderers, and so the default x64-debug preset, need. The usual cause is the wrong window: only the x64 Native Tools Command Prompt puts the Windows SDK on the path (the wrong command prompt). If where fxc finds nothing in that prompt either, the SDK is missing: add a Windows 11 SDK in the Visual Studio Installer, as step 1 of Install the tools describes, open a new prompt and configure again.

A warning that an object file path exceeds CMAKE_OBJECT_PATH_MAX

Section titled “A warning that an object file path exceeds CMAKE_OBJECT_PATH_MAX”

Configure prints CMake Warning ... The object file directory ... has N characters. The maximum full path to an object file is 250 characters (see CMAKE_OBJECT_PATH_MAX). The checkout’s folder is too deep, and the build that follows will stop with C1083. Do not raise CMAKE_OBJECT_PATH_MAX: the limit that matters is the compiler’s, which is 260 characters for the whole path. Move the checkout to a folder whose path is under 100 characters, or reach it through a drive letter as in Keeping a deep folder, delete out\build\, and configure again. In a folder deeper still, configure can fail before this, with vcpkg was unable to detect the active compiler's information, for the same reason and with the same fix.

Only the Vulkan presets need the Vulkan SDK, with VULKAN_SDK set, because they compile the shader to SPIR-V with the SDK’s dxc. Windows also ships a dxc.exe without SPIR-V support, which is why the build looks only in the SDK. If you do not need Vulkan, use the default x64-debug preset (Direct3D 11).

Configure sits at Detecting compiler hash for triplet x64-windows...

Section titled “Configure sits at Detecting compiler hash for triplet x64-windows...”

vcpkg prints this line and then nothing for many minutes. Where these pages were checked it happened while another configure on the same machine was also running Visual Studio’s vcpkg, and why was not found. One such wait ended by itself after 19 minutes, with Configuring done (1161.8s); another was stopped after half an hour, and the same configure run again later finished in 3 seconds. Leave it running for a while; if it is still there after half an hour, close the prompt with the window’s X, wait for any other build on the machine to finish, open a new prompt and configure again.

Cannot find source file: dpi_aware.manifest, or another file, after moving to a newer Labrador

Section titled “Cannot find source file: dpi_aware.manifest, or another file, after moving to a newer Labrador”

The new release’s game\CMakeLists.txt lists a file your game folder does not have yet. Update your code for a newer Labrador says where to copy it from.

Failed to load manifest and vcpkg.json:13:5: error: Unexpected character in middle of array

Section titled “Failed to load manifest and vcpkg.json:13:5: error: Unexpected character in middle of array”

A comma is missing in vcpkg.json, here before the entry on line 13. Every entry in a list but the last ends with a comma. A worked merge shows the list as it should be.

Labrador builds with warnings as errors (/W4 /WX), and a game that links labrador_settings does too. A warning in your own code is in C2220 below. If the warning is in engine code, under external\labrador, and you have not changed it, please report it with your compiler version, which the first line of cl prints.

fatal error C1083: Cannot open compiler generated file: '': Invalid argument

Section titled “fatal error C1083: Cannot open compiler generated file: '': Invalid argument”

The full path of an object file is longer than the compiler accepts, which is 260 characters whether or not long paths are enabled in Windows or in Git. The checkout’s folder is too deep, and configure will have warned about CMAKE_OBJECT_PATH_MAX. Move the checkout to a folder whose path is under 100 characters, or reach it through a drive letter as in Keeping a deep folder, then configure and build again from there.

LNK1168: cannot open game\MyGame.exe for writing

Section titled “LNK1168: cannot open game\MyGame.exe for writing”

The build’s last step stopped with these lines among others:

Output
LINK : fatal error LNK1168: cannot open game\MyGame.exe for writing
ninja: build stopped: subcommand failed.

The game is still running, from an earlier command, a double-click or Visual Studio, and Windows does not let a running program be replaced. Quit it: click its window, then press Escape, then Enter. If Visual Studio started it, stop it there with Shift+F5 instead. Then build again. If you cannot find its window, this closes it:

Terminal window
taskkill /im MyGame.exe

It prints SUCCESS: Sent termination signal to the process "MyGame.exe" and a number, or ERROR: The process "MyGame.exe" not found. if the game was not running after all. Your code was compiled before the link failed, so the build that follows only links.

A project defined its own target with that name. The engine defines it, and every target that links the engine should link the engine’s copy rather than declare another (Start your own project).

An include such as "game/states/hello_state.h" is not found

Section titled “An include such as "game/states/hello_state.h" is not found”

Includes in a Labrador project are written from the project’s root, so the folder above game\ has to be on the include path. The target_include_directories line in Start your own project adds it.

C2653: 'mattmath': is not a class or namespace name after moving to a newer Labrador

Section titled “C2653: 'mattmath': is not a class or namespace name after moving to a newer Labrador”

The engine’s math library moved from mattmath:: to labrador:: in v0.3.0, and its constants were spelt in lower case. Update your code for a newer Labrador makes every rename in your game folder with one line.

These are the errors a change to your game’s code is most likely to cause, each made on purpose in a starter project. Read a build error shows how to find the line that matters in a failed build and get to it. Fix the first error in the output and build again: the ones after it are often the same slip seen again.

Output
C:\dev\mygame\game\states\hello_state.cpp(87): error C2001: newline in string literal

A string’s closing quotation mark is missing, so the string runs on to the end of the line. Errors such as C2143 and C2059 on the next line usually follow it and go away with it. Put the quotation mark back on the line named. A string has to start and end on the same line.

C2143: syntax error: missing ';' before ...

Section titled “C2143: syntax error: missing ';' before ...”
Output
C:\dev\mygame\game\states\hello_state.cpp(50): error C2143: syntax error: missing ';' before '}'

The compiler reached the thing after before while it was still expecting the end of a statement. Look at the end of the line before the one named, and the line itself: here line 49, direction.x -= 1.0f, had lost its ;. The same message with ')' or '}' in place of ';' means a bracket of that kind is missing. After C2001 it is a consequence: fix that first.

C2065: undeclared identifier, or C3861: identifier not found

Section titled “C2065: undeclared identifier, or C3861: identifier not found”
Output
C:\dev\mygame\game\states\hello_state.cpp(87): error C2065: 'font_nam': undeclared identifier
C:\dev\mygame\game\states\hello_state.cpp(157): error C3861: 'keyboard_directon': identifier not found

The name in quotation marks is not one the compiler knows at that point. C2065 is said of a variable, C3861 of a function. In order of likelihood:

  • It is misspelt, or differs in capitals: Font_name is not font_name. Find where it is declared and copy its spelling.
  • It is declared further down the file than where you use it. Move the use, or the declaration, so the declaration comes first.
  • Its header is not included. A name from the engine or from another of your files needs that file’s #include at the top. The API reference gives the header for each engine name.
  • It is in the engine and needs labrador:: in a file that has no using namespace labrador; line.

C3646: unknown override specifier, and C4430: missing type specifier

Section titled “C3646: unknown override specifier, and C4430: missing type specifier”
Output
C:\dev\mygame\game/states/hello_state.h(74): error C3646: 'target_': unknown override specifier
C:\dev\mygame\game/states/hello_state.h(74): error C4430: missing type specifier - int assumed. Note: C++ does not support default-int

These two together mean the type in front of a name in a header, usually a member variable, is not one the compiler knows. Here Vector2F target_; was added to hello_state.h. A state’s header has no using namespace labrador; line, unlike its .cpp, so every engine type in it needs labrador:: in front: labrador::Vector2F target_;. Otherwise the type is misspelt, or its header is not included at the top. The message names the variable rather than the type, and appears once for each file that includes the header.

Output
C:\dev\mygame\game\states\hello_state.cpp(88): error C2039: 'whte': is not a member of 'labrador::Colour'
C:\dev\mygame\external\labrador\engine/render/colour.h(26): note: see declaration of 'labrador::Colour'
C:\dev\mygame\game\states\hello_state.cpp(88): error C2065: 'whte': undeclared identifier

The name after ., -> or :: is not part of the type the error names: here Colour has no whte. It is usually misspelt. The engine and the starter use British spellings, so motion_.center gives 'center': is not a member of 'Motion', where the name is centre, and the colour type is Colour. The note line names the file that declares the type: open it to see the names it has, or, for an engine type, its page in the API reference. If the name is spelt as a page of this site spells it, the page may describe a newer engine than yours: Which Labrador you have checks.

C2664: cannot convert argument, or C2665: no overloaded function could convert

Section titled “C2664: cannot convert argument, or C2665: no overloaded function could convert”
Output
C:\dev\mygame\game\states\hello_state.cpp(177): error C2664: 'void labrador::Text::set_text(const std::wstring &)': cannot convert argument 1 from 'const char [1]' to 'const std::wstring &'

A value between a call’s brackets is of a type the function does not take. The message names the function, which argument, counting from 1, and both types. The commonest cause in a Labrador game is text without its L: the engine’s text is std::wstring, a wide string, so write L"" and L"Score", not "" and "Score".

C2665 is the same mistake made through std::make_unique, which a scene’s add line uses. It starts with a file in Visual Studio’s own folder, such as ...\include\memory(3666), and is followed by dozens of notes. Look down them for the first that names a file in game\, and for the note that says cannot convert argument; Read a build error works through one.

Output
C:\dev\mygame\game\states\hello_state.cpp(155): error C2660: 'step_motion': function does not take 3 arguments
C:\dev\mygame\game/rules/motion.h(48): note: see declaration of 'step_motion'

The call has more or fewer values between its brackets than the function takes. The note names the line that declares the function: open it, count what it takes, and make the call match. Here dt had been left off the end of the call.

Output
C:\dev\mygame\game\states\hello_state.cpp(8): fatal error C1083: Cannot open include file: 'game/states/confirm_states.h': No such file or directory

An #include names a file that is not there. Check its spelling against the file in Explorer or with dir game\states. Includes in a Labrador project are written from the project’s folder, starting game/ for your files and engine/ for the engine’s, with forward slashes. If the spelling is right, check that the file is in the folder the include names: a new file of yours saved in game\ itself, rather than in game\states\, is included as game/score.h, not game/states/score.h. C1083 with Cannot open compiler generated file is a different problem, about the folder’s depth: see above.

Output
C:\dev\mygame\game\states\hello_state.cpp(67): error C2888: 'HelloState::HelloState(labrador::Application *)': symbol cannot be defined within namespace 'anonymous-namespace'
...
C:\dev\mygame\game\states\hello_state.cpp(18): fatal error C1075: '{': no matching token found

A } is missing. This is the one case where the first error is not the one to read: the compiler pairs each } with the nearest { still open, so after one goes missing every } below it closes the wrong block, and it complains about correct code below the slip. The C1075 line comes last and names the { left over at the end, which is the outermost one, not the one whose } is missing. Here the } deleted was at line 62, ending an if block, and line 18 is the { of the namespace block around the whole of keyboard_direction. The missing } is between the line C1075 names and the first error’s line. In the files you were given, each } sits directly below its { at the same indent; look in that range, in code you changed, for a { with no } under it. Read a build error shows the whole case.

C3668: did not override any base class methods, or C2511: overloaded member function not found

Section titled “C3668: did not override any base class methods, or C2511: overloaded member function not found”
Output
C:\dev\mygame\game/states/hello_state.h(33): error C3668: 'HelloState::draw': method with override specifier 'override' did not override any base class methods
C:\dev\mygame\game\states\hello_state.cpp(204): error C2511: 'void HelloState::draw(labrador::Renderer &) const': overloaded member function not found in 'HelloState'

A function is written differently in two places that have to agree. C3668 means a function marked override in a state’s header does not match the one it replaces in the engine’s State: here const had been removed from draw. A state’s init, update, draw, on_suspend and on_resume must keep the engine’s spelling exactly; draw ends const and update takes float dt. C2511 means the .cpp file defines a function the header does not declare, the same way: for example update(double dt) in the .cpp where the header says update(float dt). Copy the line from the header to the .cpp, or the other way round. Many errors about this pointers after a C2511 are its consequences.

C2220: the following warning is treated as an error

Section titled “C2220: the following warning is treated as an error”
Output
C:\dev\mygame\game\states\hello_state.cpp(81): error C2220: the following warning is treated as an error
C:\dev\mygame\game\states\hello_state.cpp(81): warning C4189: 'unused_scale': local variable is initialized but not referenced

Your game builds with warnings as errors, so C2220 stops the build because of the warning on the line after it. Fix what that warning says; do not turn the setting off. The warnings these pages’ checks met:

Warning What it means Fix
C4189: local variable is initialized but not referenced A variable is made and never used. Use it, or delete it.
C4100: unreferenced parameter A function takes a value it never uses. Use it, or delete its name and keep its type: void flash(float).
C4305: 'initializing': truncation from 'double' to 'const float' A number without f where a float is meant. Write 1.2f, not 1.2.
C4244: conversion from 'float' to 'int', possible loss of data A float put into an int, which drops the fraction. Keep it a float, or write static_cast<int>(...) to say the fraction should go.

A warning in a header, such as game\rules\motion.h, appears once for every file that includes it, each under its own FAILED: line. It is one warning to fix.

Output
hello_state.cpp.obj : error LNK2019: unresolved external symbol "int __cdecl starting_score(void)" (?starting_score@@YAHXZ) referenced in function "public: virtual void __cdecl HelloState::init(void)" (?init@HelloState@@UEAAXXZ)
game\MyGame.exe : fatal error LNK1120: 1 unresolved externals

Every file compiled, but the linker found no body for a function the game uses: here starting_score, used in HelloState::init. LNK1120 counts these lines. The causes, in order of likelihood:

  • A new .cpp file is not in the build. Every source file is listed by name in game\CMakeLists.txt, and the game’s sources are listed twice: in the add_executable(MyGame inside if(EMSCRIPTEN), for the browser, and in the add_executable(MyGame WIN32 after it, for Windows. Add the file’s name, such as states/score.cpp, beside states/hello_state.cpp in both, save, and build again. The build reads the changed list by itself. Add a screen to your game shows both edits.
  • The function is declared in a header but never written in any .cpp, or the .cpp spells it differently: a different name, different parameter types, or a member function written without its class, int score() where int HelloState::score() was meant.

To tell which, list every line in your game that has the function’s name, with this, from your project’s folder and with the name from the error in place of starting_score:

Terminal window
findstr /s /n "starting_score" game\*.cpp game\*.h

Each line it prints is a file, a line number and the line. Where the name is used, as in starting_score();, is the call. Where it ends in ; after its brackets in a .h file is the declaration. Where it is followed by a { on the next line, in a .cpp file, is the body. If there is no body, write it. If there is one, compare its first line with the declaration, then check that its .cpp file is in both lists. If findstr prints nothing, the name in the error is spelt differently from what you searched for.

  • The tests need a file that only the game lists. When the FAILED: line names game/MyGameTests.exe rather than game/MyGame.exe, the function is in a file the tests also use. Such a file goes in add_library(MyGameRules, as rules/motion.cpp does, and not in the two game lists.

The browser build’s linker says the same thing as undefined symbol.

On Windows, a problem the game finds while it loads shows in two places. ctest’s start-up test fails, with a line under it starting startup failure: that gives the reason. Started on its own, the game shows the same reason in a box titled Sample - startup failure, whatever the game is called, and closes when OK is clicked. Started from Visual Studio, the box is the same, and the debugger can show the line of yours that led to it: When the game shows an error. In the browser build the page shows the reason in red in place of the game, and the browser’s console has it after MinimalSample:. The messages below and under Content are that reason.

read_json_file - cannot open '...manifest.json', or a file in the manifest is missing

Section titled “read_json_file - cannot open '...manifest.json', or a file in the manifest is missing”

The content was not copied beside the executable. A sound bank’s .json file, such as read_json_file - cannot open '...\game\.\./sounds/tones.json', is the same: a folder not copied, or a misspelt name or directory in the manifest. The build copies it with a custom target (Getting content beside the executable); check that your CMakeLists.txt has the copy lines for every content folder, and build again. In game\CMakeLists.txt the starter copies its one folder, fonts, with this block:

game\CMakeLists.txt
add_custom_command(TARGET game_content POST_BUILD
COMMAND "${CMAKE_COMMAND}" -E copy_directory_if_different
"${CMAKE_CURRENT_SOURCE_DIR}/content/fonts"
"$<TARGET_FILE_DIR:MyGame>/fonts"
VERBATIM
)

A folder you added, such as game\content\textures, needs the same block under it with the folder’s name in both places, content/textures and /textures, before the add_dependencies(MyGame game_content) line:

game\CMakeLists.txt
add_custom_command(TARGET game_content POST_BUILD
COMMAND "${CMAKE_COMMAND}" -E copy_directory_if_different
"${CMAKE_CURRENT_SOURCE_DIR}/content/textures"
"$<TARGET_FILE_DIR:MyGame>/textures"
VERBATIM
)

Save, build, and check that the folder is now beside the game:

Terminal window
cmake --build --preset x64-debug && dir out\build\x64-debug\game

dir lists the folder’s contents in alphabetical order. Among them is a line for each folder copied, such as fonts and textures, with <DIR> where a file’s size would be:

Output
31/10/26 08:09 <DIR> fonts
31/10/26 08:30 361 manifest.json
31/10/26 08:37 2,429,952 MyGame.exe
...
31/10/26 08:37 <DIR> textures

Put a picture in your game and Play a sound in your game each go through this with the install and browser lines a new folder also needs.

Code resolved a name that is not in the manifest, such as Texture 'heroo' was never loaded., Font 'jetbrains_mono_bold32' was never loaded. or SoundBank 'tone' was never loaded. The message names the asset; check its spelling in the code and in manifest.json, which must match exactly and leave off the file extension. SoundEffect 'drone_lop' was never loaded. names an effect instance the bank’s .json file does not list under sound_effect_instances.

A handle was used before it was resolved, usually because a drawable was default-constructed or built before the manifest was loaded. Build drawables in a state’s init() (States and the stack).

The window opens and nothing moves when I press keys

Section titled “The window opens and nothing moves when I press keys”

Keys are read once per step, and a key pressed and released between two steps is not seen. More often the cause is reading pressed where held was meant, or the other way round (Held, pressed and released). If only the gamepad is ignored on Windows, check that it is XInput-compatible: a controller using another pad API does not appear. Then check which slots the game reads. A lone pad can occupy a higher slot, and a replug can change its slot; the input guide’s single-player pattern reads all four.

The game runs and a sound it plays is not heard. Check that the game’s window is in front when the key is pressed, that Windows’ volume is up and not muted and its output is the one you are listening to, that the game is not turned down in the Volume mixer, and that the build is not a -null preset, which plays nothing on purpose. With no output device when it starts, the game runs silently, and the engine looks for one again once a second. No sound, and no error has the whole list.

The window opens, or the game runs for a while, and then it is gone with no box. The game has crashed: most often it used an object through a pointer that holds nullptr. The window can stay, not answering, for half a minute or more first, while Windows records the crash. Started from the prompt in C:\dev\mygame with these two lines, the first of which waits until the game has ended:

Terminal window
start /wait "" out\build\x64-debug\game\MyGame.exe
echo %ERRORLEVEL%

the exit code printed is -1073741819, Windows’ code for a program that used memory it may not use. Run it under Visual Studio’s debugger with F5, which stops on the line where it happened: When the game closes with no message.

No Direct3D hardware device found in a release build

Section titled “No Direct3D hardware device found in a release build”

The release build does not fall back to Microsoft’s software renderer, WARP; the debug build does. Update the graphics driver, or use a debug build on a machine without a usable graphics adapter.

include could not find requested file: /upstream/emscripten/...

Section titled “include could not find requested file: /upstream/emscripten/...”

With EMSDK unset, configuring a wasm-* preset prints:

include could not find requested file:
/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake

EMSDK should be the part before /upstream. Run emsdk_env.bat in the same x64 Native Tools Command Prompt as CMake, check echo %EMSDK% and emcc --version, then configure again; the half-made browser build folder does not need deleting. Set EMSDK in your build prompt has the commands. Address the missing toolchain before investigating the Ninja and compiler errors that follow it.

The same lines in Visual Studio’s Output, after CMake generation started for configuration: 'wasm-debug-wasm-debug'., mean its configuration box says wasm-debug: choose x64-debug there, as Edit and debug in Visual Studio says. The browser build is built from the prompt.

Installing Emscripten: 'git', 'python' or 'emsdk' is not recognized

Section titled “Installing Emscripten: 'git', 'python' or 'emsdk' is not recognized”

'git' is not recognized comes from cloning emsdk without Git: download its ZIP with curl and tar instead, as Install Emscripten does. 'python' is not recognized, or Python was not found; run without arguments to install from the Microsoft Store, from emsdk install means emsdk’s first run found no Python: install it as that page’s step 1 says and open a new prompt. 'emsdk' is not recognized means the prompt is not in C:\dev\emsdk. Each of emsdk’s own error: lines, a duplicate folder and a failed download are under If something fails.

PermissionError: [WinError 10013] when serving the page

Section titled “PermissionError: [WinError 10013] when serving the page”

Python’s server could not use port 8000, because another program holds it. Use 8001 in the command and in the address. Started with start, the server’s window closes at once instead: run the command without start "MyGame server" to see the message. A second Python server on a port one already uses starts with no error, and the first goes on answering; Serve it and open it has the commands.

'"%EMSDK_PYTHON%"' is not recognized, or Windows cannot find '%EMSDK_PYTHON%'

Section titled “'"%EMSDK_PYTHON%"' is not recognized, or Windows cannot find '%EMSDK_PYTHON%'”

The prompt has not run emsdk_env.bat, as in a new prompt or the next day; "%EMSDK_NODE%" gives the same from the page runner or the bundler. The second message is a box that start opens in place of the server’s window: click OK. Run C:\dev\emsdk\emsdk_env.bat in this prompt and the command again, as If something fails says.

The page shows the old game after a rebuild

Section titled “The page shows the old game after a rebuild”

F5 asks the server again only for the page, and the browser keeps the old .js and .wasm. Reload with Ctrl+F5. Change it, rebuild and refresh says what was measured.

Error response, Error code: 404, Message: File not found.

Section titled “Error response, Error code: 404, Message: File not found.”

The browser shows this when the server has no such file: it was started from another folder, so its --directory points at nothing, or the page is not built. Close the server, cd /d C:\dev\mygame, check dir out\build\wasm-debug\game\MyGame.html, and start it again. An older server still open on the same port gives it too, for the samples’ pages as Run the samples says. A 404 for favicon.ico alone is harmless.

The page stays at Loading... when opened from file://

Section titled “The page stays at Loading... when opened from file://”

Double-clicking the generated HTML file is not enough. In Chrome, the minimal sample stays at Loading..., and the developer console includes:

Aborted(Assertion failed: readAsync does not work with file:// URLs)
Aborted(both async and sync fetching of the wasm failed)

The browser refused to fetch the .wasm file from a local-file URL. Serve the build folder over HTTP and open its http://127.0.0.1:... address instead, as in Serve it and open it. Keep the generated HTML, JavaScript and WebAssembly files together.

ctest lists fewer tests, with no page tests

Section titled “ctest lists fewer tests, with no page tests”

When configuring the engine checkout without a Chromium, CMake prints:

No Chromium found, so RenderPixelTests, RenderPixelTestsWithoutS3tc, RenderContextLossTests, WebWindowTests and the samples' pages are built and not registered with ctest. Set LABRADOR_TEST_BROWSER to run them.

For the engine’s default browser configurations, ctest --preset wasm-debug -N then lists 19 tests instead of 32; Release lists 19 instead of 33. These are absent entries, not skipped or passing page tests. The remaining tests run under Node, which cannot check drawing or page input. The counts describe the engine checkout; the copied Get Started project has one rules test and does not register these engine tests.

Install Chrome or point configure at a Chromium executable, such as Edge, then build and test again. For example:

Terminal window
cmake --preset wasm-debug -DLABRADOR_TEST_BROWSER="C:/Program Files/Google/Chrome/Application/chrome.exe"
cmake --build --preset wasm-debug
ctest --preset wasm-debug

LABRADOR_TEST_BROWSER is a CMake cache variable, not an environment variable. Check the configure message and test names as well as the total, because new tests can change the count.

This browser would not give the canvas a WebGL2 context.

Section titled “This browser would not give the canvas a WebGL2 context.”

The minimal sample displays this message in its page and writes it to the console when WebGL2 is disabled. The full error says WebGL2 may be turned off or the browser may have blocked the GPU. Check the browser’s graphics settings and driver, then reload. The browser build needs WebGL2; WebGL1 is not a fallback. If it still fails, report the browser version and its graphics diagnostics with the error. A successful CMake build does not prove that the browser can make a graphics context.

Output
wasm-ld: error: game/CMakeFiles/MyGame.dir/states/hello_state.cpp.o: undefined symbol: starting_score()

The browser build’s form of LNK2019, with the same causes. The commonest is a new .cpp file listed for Windows in game\CMakeLists.txt but not in the add_executable(MyGame inside if(EMSCRIPTEN), so the Windows build works and this one does not. Clang’s compiler errors look different from the Windows ones too: In the browser build reads one.

A title-screen sound is silent, and does not play after the first key

Section titled “A title-screen sound is silent, and does not play after the first key”

Before the page has a qualifying key, click or touch, Web Audio has no context to play through. SoundBank::play_wave drops a one-shot requested then; it does not save it for the first gesture, and the engine does not log an error. A persistent play_effect waits, including a loop, unless it is paused or stopped immediately with stop_effect(effect, true) first. Escape alone does not unlock sound. Start a title jingle after the player’s start gesture, or use a persistent effect when waiting is intended. Browser audio and the first gesture states the contract and how it applies to the game’s sounds.

Put a picture in your game, Animate a sprite sheet, Fonts and text in your game and Play a sound in your game show where each of these messages comes from in a starter project, made on purpose.

'texconv' is not recognized as an internal or external command

Section titled “'texconv' is not recognized as an internal or external command”

The prompt cannot find the program by its short name. Either it is not downloaded yet, or it is in C:\dev\tools and the prompt was not told to look there. Run it by its full path, C:\dev\tools\texconv.exe, or follow Install the content tools. The same goes for MakeSpriteFont and xwbtool.

reading ... FAILED (80070002: The system cannot find the file specified. )

Section titled “reading ... FAILED (80070002: The system cannot find the file specified. )”

texconv found no file with that name in the folder the prompt is in. Check the folder with cd and the name with dir, which shows the whole name, including an extension File Explorer hides.

writing ... FAILED (80070003: The system cannot find the path specified. )

Section titled “writing ... FAILED (80070003: The system cannot find the path specified. )”

The folder after texconv’s -o does not exist. Make it with mkdir, then run texconv again.

ERROR: Output file already exists, use -y to overwrite:

Section titled “ERROR: Output file already exists, use -y to overwrite:”

texconv will not replace a file unless the command has -y. Add it. xwbtool says the same as ERROR: Output file ... already exists, use -y to overwrite!, and needs the same -y.

... uses the DX10 extended header, which this engine does not read.

Section titled “... uses the DX10 extended header, which this engine does not read.”

The texture was converted without -f R8G8B8A8_UNORM, so texconv kept the PNG’s sRGB format, which needs that header. Convert it again with the command in Put a picture in your game, which also has --ignore-srgb.

... is not a .dds, ... is a 32-bit image with channel masks, ... is in fourCC format, or ... stores 16 bits a pixel

Section titled “... is not a .dds, ... is a 32-bit image with channel masks, ... is in fourCC format, or ... stores 16 bits a pixel”

The texture is in a form the engine does not read: a PNG or other picture renamed to .dds, a picture with no transparency channel, or a format such as BC4 or a 16-bit one. Convert the picture again with the command in Put a picture in your game, which writes a format the engine reads.

The manifest names a file the game cannot find beside itself; the path in the message is where it looked. A misspelt name or directory in manifest.json, a file never converted, or a folder the build does not copy all give this. A new content folder needs a copy line in game\CMakeLists.txt, as Put a picture in your game adds for textures.

A JSON file, such as the manifest or a sprite sheet’s .json, has a punctuation mistake: a missing or extra comma, quotation mark or bracket. The words after it say what the reader expected, and offset counts characters from the start of the file to where it gave up, which is after the mistake. Missing a comma or ']' after an array element. is often a missing comma between two groups; Invalid value. is often a comma after a list’s last entry.

Asset ... is of kind ..., which nothing registered.

Section titled “Asset ... is of kind ..., which nothing registered.”

The manifest’s kind is misspelt. The engine knows texture, font, sprite_sheet and sound_bank; any other kind is one the game registers itself (A kind of asset of your own).

A sprite sheet’s .json has a field the engine does not read, usually a misspelling, such as animation_strips[0] has unknown key 'frame_cont'. The message names the list and the entry, counting from 0. Sprites from a sheet lists the fields.

no animation strip named ..., or no sprite frame named ...

Section titled “no animation strip named ..., or no sprite frame named ...”

The name in the code does not match one in the sprite sheet’s .json.

Animation frame index 0 is outside a strip of 0.

Section titled “Animation frame index 0 is outside a strip of 0.”

A strip in a sprite sheet’s .json has a frame_count of 0. Make it the number of frames in the strip.

MakeSpriteFont found no installed font with that family name. Install the font, and give its family name, such as "JetBrains Mono", not a face’s full name such as "JetBrains Mono Bold" (Fonts and text in your game).

The font atlas the text uses has no glyph for that letter. The starter’s holds only printable English characters. Make an atlas with a /CharacterRegion that covers the letter (Letters beyond English). A letter read from a file also draws as ? when the file was not saved as UTF-8.

This font has no glyph for ... and no stand-in to draw instead.

Section titled “This font has no glyph for ... and no stand-in to draw instead.”

The atlas has neither the letter nor a ? or space to draw in its place, which happens when it was made with /CharacterRegion options that leave out the English range. Make it again with /CharacterRegion:0x20-0x7e as well (Letters beyond English).

A picture’s colours are darker than in the PNG

Section titled “A picture’s colours are darker than in the PNG”

The texture was converted without --ignore-srgb, so texconv darkened every colour between full and none. Convert it again with the command in Put a picture in your game.

A sprite has a fringe or halo round its soft edges

Section titled “A sprite has a fringe or halo round its soft edges”

The texture was not premultiplied when it was converted. The engine blends premultiplied and does not premultiply a texture at load, so convert it again with texconv’s -pmalpha (Colours and blending). The same cause shows a fully transparent area as a coloured box. Edges that come out darker than they should are the opposite mistake: a source that was already premultiplied, premultiplied again.

The sound bank’s .json file is beside the game and its .xwb file is not, or the .xwb is not a wave bank. Copy or pack the bank again (Play a sound in your game) and build. In the browser build the same words begin the reader’s own messages, such as the compact-entries one below.

A name in the bank’s .json file’s waves is not in the .xwb: either xwbtool was run without -f, so the bank holds no names, or the name is not the WAV file’s name without .wav, spelt exactly, capitals included. Pack the bank again with xwbtool -f -nc -y, or fix the name.

The name in the code’s resolve_wave is not one in the bank’s .json file’s waves. Fix the spelling in the code.

A JSON file lacks an entry the engine needs, which the message names. A sound bank’s .json file needs all three of waves, create_effect_instance_for_each_wave and sound_effect_instances, even when the last is [].

ERROR: Wave banks do not support IEEE float PCM data, ... only support 8-bit or 16-bit integer PCM data, or ERROR: Failed to load file (80004005: Unspecified error )

Section titled “ERROR: Wave banks do not support IEEE float PCM data, ... only support 8-bit or 16-bit integer PCM data, or ERROR: Failed to load file (80004005: Unspecified error )”

xwbtool takes WAV files holding 8-bit or 16-bit PCM. The first two are a 32-bit float or a 24-bit WAV; the third a file that is not a WAV at all, such as an MP3, whatever its name ends with. Export the sound again as 16-bit PCM, or convert it with FFmpeg (Sounds xwbtool will not take).

... uses compact entries, which this engine does not read

Section titled “... uses compact entries, which this engine does not read”

The wave bank was packed without -nc. Windows plays a compact bank and the browser build does not, because it reads banks with the engine’s own reader. Pack it again with xwbtool -f -nc (Make sound content and verify it).

... Hz, which this browser's Web Audio cannot hold

Section titled “... Hz, which this browser's Web Audio cannot hold”

A wave in the bank is at a sample rate the browser will not make a buffer for. Export it at a rate between 8,000 and 96,000 Hz, which every browser accepts, and pack the bank again (Exporting sounds both platforms play).

These come from Send your game to a friend, Put your project on GitHub and Put your game on the web, which give each in full.

error: src refspec main does not match any

Section titled “error: src refspec main does not match any”

The project has no branch called main: the branch is still master, or there is no commit yet. Run git branch -M main, or make the first commit, then push again (Put your project on GitHub).

fatal: Authentication failed, after Invalid username or token. Password authentication is not supported

Section titled “fatal: Authentication failed, after Invalid username or token. Password authentication is not supported”

Git sent a username and password, which GitHub does not accept from Git. Push again and use Sign in with your browser in the Connect to GitHub window (Put your project on GitHub).

The address in git remote -v names no repository your sign-in can see: a misspelt username or name, or a repository not yet made. Fix it with git remote set-url origin and the right address.

The repository on GitHub was made with a README, .gitignore or licence. For a new repository holding nothing else, git push -u --force origin main replaces them (Put your project on GitHub).

SmartScreen’s warning on a program downloaded from the internet and not signed. The player clicks More info, then Run anyway (What your friend does).

The code execution cannot proceed because DirectXTK.dll was not found.

Section titled “The code execution cannot proceed because DirectXTK.dll was not found.”

The game was started without the files beside it, usually from inside the ZIP. Extract the ZIP with Extract All… and start the game from the extracted folder.

404 and There isn't a GitHub Pages site here.

Section titled “404 and There isn't a GitHub Pages site here.”

GitHub Pages is not turned on for the repository yet, its first publish has not finished, or the address is wrong. It is https:// + username + .github.io/ + repository + / (Put your game on the web).

Documentation for Labrador v0.3.0. Built from Labrador 0f4f503 of 2026-11-03.

All documentation versions