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.
Error opening archive: Failed to open
Section titled “Error opening archive: Failed to open”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.
This does not look like a tar archive
Section titled “This does not look like a tar archive”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:
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:
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\mygameThe 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.
A suitable version of git was not found
Section titled “A suitable version of git was not found”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.
Setting up and cloning
Section titled “Setting up and cloning”Filename too long while cloning
Section titled “Filename too long while cloning”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).
The wrong command prompt
Section titled “The wrong command prompt”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:
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 errorC:\dev\Labrador\tests\app\window_tests.cpp(477): warning C4309: 'argument': truncation of constant valueYour 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:
rmdir /s /q out\build\x64-debugcmake --preset x64-debugcmake --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.
Author identity unknown
Section titled “Author identity unknown”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.
You are in 'detached HEAD' state
Section titled “You are in 'detached HEAD' state”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:
git submodule update --init --recursivecmake --preset x64-debugThe 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.
Configuring
Section titled “Configuring”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”CMake Error: Could not read presets from C:/dev:File not found: C:/dev/CMakePresets.jsonThe 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:
cd /d C:\dev\mygameThe 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:
rmdir /s /q out\build\x64-debugcmake --preset x64-debugIn Visual Studio rather than the prompt, the fix is the same setx line in that section,
followed by closing and reopening Visual Studio.
No Direct3D shader compiler (fxc)
Section titled “No Direct3D shader compiler (fxc)”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.
A preset fails on dxc or the Vulkan SDK
Section titled “A preset fails on dxc or the Vulkan SDK”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.
Building
Section titled “Building”A warning stops the build in engine code
Section titled “A warning stops the build in engine code”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:
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:
taskkill /im MyGame.exeIt 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.
labrador_settings is defined twice
Section titled “labrador_settings is defined twice”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.
Errors in your own code
Section titled “Errors in your own code”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.
C2001: newline in string literal
Section titled “C2001: newline in string literal”C:\dev\mygame\game\states\hello_state.cpp(87): error C2001: newline in string literalA 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 ...”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”C:\dev\mygame\game\states\hello_state.cpp(87): error C2065: 'font_nam': undeclared identifierC:\dev\mygame\game\states\hello_state.cpp(157): error C3861: 'keyboard_directon': identifier not foundThe 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_nameis notfont_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
#includeat 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 nousing namespace labrador;line.
C3646: unknown override specifier, and C4430: missing type specifier
Section titled “C3646: unknown override specifier, and C4430: missing type specifier”C:\dev\mygame\game/states/hello_state.h(74): error C3646: 'target_': unknown override specifierC:\dev\mygame\game/states/hello_state.h(74): error C4430: missing type specifier - int assumed. Note: C++ does not support default-intThese 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.
C2039: is not a member of
Section titled “C2039: is not a member of”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 identifierThe 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”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.
C2660: function does not take N arguments
Section titled “C2660: function does not take N arguments”C:\dev\mygame\game\states\hello_state.cpp(155): error C2660: 'step_motion': function does not take 3 argumentsC:\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.
C1083: Cannot open include file
Section titled “C1083: Cannot open include file”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 directoryAn #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.
C1075: '{': no matching token found
Section titled “C1075: '{': no matching token found”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 foundA } 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”C:\dev\mygame\game/states/hello_state.h(33): error C3668: 'HelloState::draw': method with override specifier 'override' did not override any base class methodsC:\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”C:\dev\mygame\game\states\hello_state.cpp(81): error C2220: the following warning is treated as an errorC:\dev\mygame\game\states\hello_state.cpp(81): warning C4189: 'unused_scale': local variable is initialized but not referencedYour 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.
LNK2019: unresolved external symbol
Section titled “LNK2019: unresolved external symbol”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 externalsEvery 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
.cppfile is not in the build. Every source file is listed by name ingame\CMakeLists.txt, and the game’s sources are listed twice: in theadd_executable(MyGameinsideif(EMSCRIPTEN), for the browser, and in theadd_executable(MyGame WIN32after it, for Windows. Add the file’s name, such asstates/score.cpp, besidestates/hello_state.cppin 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.cppspells it differently: a different name, different parameter types, or a member function written without its class,int score()whereint 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:
findstr /s /n "starting_score" game\*.cpp game\*.hEach 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 namesgame/MyGameTests.exerather thangame/MyGame.exe, the function is in a file the tests also use. Such a file goes inadd_library(MyGameRules, asrules/motion.cppdoes, and not in the two game lists.
The browser build’s linker says the same thing as
undefined symbol.
Running
Section titled “Running”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:
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:
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:
cmake --build --preset x64-debug && dir out\build\x64-debug\gamedir 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:
31/10/26 08:09 <DIR> fonts31/10/26 08:30 361 manifest.json31/10/26 08:37 2,429,952 MyGame.exe...31/10/26 08:37 <DIR> texturesPut 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.
... was never loaded
Section titled “... was never loaded”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.
... was read through an unresolved handle
Section titled “... was read through an unresolved handle”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.
No sound, and no error
Section titled “No sound, and no error”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 game closes with no message
Section titled “The game closes with no message”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:
start /wait "" out\build\x64-debug\game\MyGame.exeecho %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.
Browser builds
Section titled “Browser builds”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.cmakeEMSDK 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:
cmake --preset wasm-debug -DLABRADOR_TEST_BROWSER="C:/Program Files/Google/Chrome/Application/chrome.exe"cmake --build --preset wasm-debugctest --preset wasm-debugLABRADOR_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.
wasm-ld: error: ... undefined symbol
Section titled “wasm-ld: error: ... undefined symbol”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.
Content
Section titled “Content”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.
No file at ...
Section titled “No file at ...”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.
read_json_file - ... is not valid JSON:
Section titled “read_json_file - ... is not valid JSON:”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).
... has unknown key ...
Section titled “... has unknown key ...”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.
Error: Can't find font '...'.
Section titled “Error: Can't find font '...'.”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).
Text draws ? in place of a letter
Section titled “Text draws ? in place of a letter”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.
Failed to open wave bank: ...
Section titled “Failed to open wave bank: ...”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.
Wave bank '...' has no wave named '...'.
Section titled “Wave bank '...' has no wave named '...'.”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.
Wave '...' is not in this sound bank.
Section titled “Wave '...' is not in this sound bank.”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.
... the document has no '...'
Section titled “... the document has no '...'”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).
Sharing the game
Section titled “Sharing the game”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).
remote: Repository not found.
Section titled “remote: Repository not found.”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.
! [rejected] main -> main (fetch first)
Section titled “! [rejected] main -> main (fetch first)”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).
Windows protected your PC
Section titled “Windows protected your PC”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.