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. The page is long: press Ctrl+F and type three or four words from the first line
that says error, not the whole line and not your own folder names, to jump to its entry. 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.
Not the starter ZIP
Section titled “Not the starter ZIP”A release page on GitHub lists more files than the starter ZIP, and two of them are easy to
take for it. Neither holds a mygame folder:
- A file called
Labrador-and a version, such asLabrador-0.3.0.ziporLabrador-master.zip, came from GitHub’s Source code (zip) link or the repository’s Code button. It is the engine on its own, not a project. - A file whose name begins
labrador-docs-, such aslabrador-docs-v0.3.0.tar.gz, is a copy of this website as it was at that release, which the site already serves: its Documentation version menu opens it. You do not need it.
Delete the wrong file, then download the file whose name begins labrador-starter-, as step 2
of Get the starter project says. If you extracted the wrong file
already, delete what it made: a Labrador- folder from Source code, or, from the
documentation copy, the loose files and folders it unpacked, such as index.html, _astro,
docs and pagefind.
C:\dev\mygame already exists. Nothing was extracted.
Section titled “C:\dev\mygame already exists. Nothing was extracted.”Step 3 of Get the starter project found a project called mygame
in C:\dev already, and left it as it was rather than put the starter’s files back over your
changes. To start another project beside it, follow
A second project. To take a newer engine into
the project you have, follow
Move a starter project to a newer Labrador.
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:
if exist C:\dev\mygame (echo C:\dev\mygame already exists. Nothing was moved.) else (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 it prints
C:\dev\mygame already exists. Nothing was moved., then The directory is not empty., you
already have a project called mygame, and the list is that project’s files, left as they
were. The new copy is still in the folder named after the ZIP: delete that folder in File
Explorer, then follow A second project.
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: Labrador needs the 64-bit compiler
Section titled “A 32-bit prompt: Labrador needs the 64-bit compiler”The plain Developer Command Prompt, Developer PowerShell and the x86 prompts set up the
32-bit compiler. cmake --preset x64-debug then says vcpkg is
Detecting compiler hash for triplet x86-windows..., builds 32-bit copies of the engine’s
libraries, and stops with:
Labrador needs the 64-bit compiler, and this build folder has a 32-bit one: C:/Program Files/Microsoft Visual Studio/18/Community/VC/Tools/MSVC/14.51.36231/bin/Hostx86/x86/cl.exe. Open the x64 Native Tools Command Prompt, delete the build folder C:/dev/mygame/out/build/x64-debug and configure again.The line above it starts CMake Error at external/labrador/CMakeLists.txt, or at
CMakeLists.txt when you build Labrador itself. The build folder remembers the compiler it was
made with, so configuring again in the right prompt is not enough. 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-debugA project on a Labrador older than this check, such as the v0.3.0 starter, configures in a
32-bit prompt without an error and builds a 32-bit game. Its next build in the right prompt
fails with warning LNK4272, and the
same three lines cure it.
'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”The git -C external/labrador checkout line 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.
The current CMakeCache.txt directory ... is different than the directory ... where CMakeCache.txt was created
Section titled “The current CMakeCache.txt directory ... is different than the directory ... where CMakeCache.txt was created”CMake Error: The current CMakeCache.txt directory C:/dev/thirdgame/out/build/x64-debug/CMakeCache.txt is different than the directory c:/dev/mygame/out/build/x64-debug where CMakeCache.txt was created.The project’s folder was moved or renamed after it was built, here from C:\dev\mygame to
C:\dev\thirdgame, and the build folder inside it still names the old place. Configuring adds
does not match the source ... used to generate cache; building adds
The source directory "C:/dev/mygame" does not appear to contain CMakeLists.txt. and
ninja: error: rebuilding 'build.ninja': subcommand failed. Do not edit CMakeCache.txt.
From the project’s folder in its new place, delete the build folders and configure again, with
your folder’s name in place of thirdgame:
cd /d C:\dev\thirdgamermdir /s /q outcmake --preset x64-debugcmake --build --preset x64-debugA build that failed this way also makes a folder with the old name, holding only empty
folders. It is not your project;
Rename your game has a line that deletes it only
if it has no game folder in it.
is not a directory, build tool execution failed, loading 'build.ninja', or No tests were found!!!
Section titled “is not a directory, build tool execution failed, loading 'build.ninja', or No tests were found!!!”The build and test lines print these when the configure before them did not finish, or was never run. Which one the build prints depends on how far configure got:
Error: C:/dev/mygame/out/build/x64-debug is not a directorywhen there was no configure at all;no such file or directory, thenCMake Error: Generator: build tool execution failed, command was:, when configure failed early, for example withVCPKG_ROOTnot set or in a folder far too deep;ninja: error: loading 'build.ninja': The system cannot find the file specified.when it failed later, for example with C1083 in a deep folder.
ctest --preset x64-debug then prints Test project C:/dev/mygame and
No tests were found!!!, and does not count that as a failure. None of these lines is the
cause, and none says FAILED. Run cmake --preset x64-debug again in the project’s folder and
read it to the end. If it ends Configuring incomplete, errors occurred!, look up its first
line that says Error on this page, then configure, build and test again.
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. The same Ninja and compiler
lines also end a configure in
a folder far too deep; the
first error line tells the two apart. 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.
error: curl operation failed with error code
Section titled “error: curl operation failed with error code”The first configure downloads the engine’s libraries and some tools, from github.com,
nuget.org and mirror.msys2.org among others, and one of the downloads failed. A name that
could not be looked up, for example, prints:
error: curl operation failed with error code 6 (Could not resolve hostname).error: Not a transient network error, won't retry download from ...note: If you are using a proxy, please ensure your proxy settings are correct.A list of Possible causes about HTTPS_PROXY and proxy programs follows. It is the
connection, not your setup: unless you know you use a proxy, ignore that list. Check that the
PC is online, then, from the project’s folder, delete the half-configured build folder and
configure again:
rmdir /s /q out\build\x64-debugcmake --preset x64-debugvcpkg keeps what it had already downloaded and built outside the project, so it carries on from there. On a school or work network that blocks those addresses, configure on another connection once; later configures use what vcpkg kept.
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 project’s folder
is deeper than these pages allow for. Do not raise CMAKE_OBJECT_PATH_MAX: the limit that
matters is the compiler’s, which is 260 characters for the whole path. What follows depends on
how deep the folder is. In a v0.3.0 starter project:
- with a folder path of 145 characters, configure printed the warning, and the project built and passed its tests;
- with 150 characters, configure itself failed with
C1083 inside
is not able to compile a simple test program; - with 158 characters or more, configure failed earlier, with
vcpkg was unable to detect the active compiler's information.
A build that does get going can still stop with
C1083 later, when a
file with a longer name is compiled. The cure is the same in every case: move the project to a
folder whose path is under 100 characters. For the starter project that is C:\dev\mygame:
move the mygame folder there in File Explorer (cut it, open C:\dev, paste), then open a new
x64 Native Tools Command Prompt and run:
cd /d C:\dev\mygamermdir /s /q outcmake --preset x64-debugrmdir deletes the build folders, which still name the old place, and prints
The system cannot find the file specified. if configure never made them. For a checkout of
Labrador, move it to C:\dev\Labrador and run the same lines from there. A deep folder you must
keep can be reached through a drive letter instead, as in
Keeping a deep folder.
vcpkg was unable to detect the active compiler's information
Section titled “vcpkg was unable to detect the active compiler's information”A configure in a very deep folder stops with lines like these, among others:
error: while detecting compiler information:...Error code: no such file or directory...error: vcpkg was unable to detect the active compiler's information.and ends with the same two lines as when
VCPKG_ROOT is not set:
CMake Error: CMake was unable to find a build program corresponding to "Ninja". and
CMake Error: CMAKE_CXX_COMPILER not set, after EnableLanguage. Here they are consequences of
the folder’s depth, not of a missing tool. Move the project as in
the warning about CMAKE_OBJECT_PATH_MAX
above, and configure again.
The C++ compiler ... is not able to compile a simple test program
Section titled “The C++ compiler ... is not able to compile a simple test program”Configure tried to compile a one-line program and the compiler refused. When the lines under
it include fatal error C1083: Cannot open compiler generated file: '': Invalid argument, the
project’s folder is too deep: move it as in
the warning about CMAKE_OBJECT_PATH_MAX
above, which configure will have printed first, and configure again. For any other error under
it, check that the window is
the x64 Native Tools Command Prompt, then
ask for help with the whole output.
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 project’s folder is too deep,
and configure will have warned about
CMAKE_OBJECT_PATH_MAX.
It can appear while building, under a FAILED line, or during configure, inside
is not able to compile a simple test program.
Move the project to a folder whose path is under 100 characters, as that warning’s entry
shows, 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.
The game has not changed after an edit, and the build printed no Building line
Section titled “The game has not changed after an edit, and the build printed no Building line”The build compiles only the files that changed since the last build. When it finds none, it prints only its last steps, in a starter project these two:
[1/2] Running utility command for game_content[2/2] Checking that no engine file includes a game headerwith no Building or Linking line, and then the tests pass and the game opens as before. The
edit never reached the file the build reads: it was not saved, or it was made in another file
of the same name, such as a copy outside C:\dev\mygame\game. Open the file from the project’s
game folder again, check that your edit is there, press Ctrl+S, and run the build again.
A build that compiles your change prints a line such as
[3/4] Building CXX object game\CMakeFiles\MyGame.dir\states\hello_state.cpp.obj naming the
file.
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. Hundreds of them at
once, naming functions you never wrote, such as __purecall or operator new, are not this
entry: see warning LNK4272. 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.
warning LNK4272 and hundreds of unresolved externals
Section titled “warning LNK4272 and hundreds of unresolved externals”LabradorMath.lib(quad.cpp.obj) : error LNK2001: unresolved external symbol _purecall......\lib\x86\MSVCRTD.lib : warning LNK4272: library machine type 'x86' conflicts with target machine type 'x64'game\MyGame.exe : fatal error LNK1120: 209 unresolved externalsThe build compiled your change and then failed to link with well over a thousand LNK2001 and
LNK2019 lines, about engine and Windows functions rather than yours. Your code is not at
fault: the build ran in a 32-bit prompt, such as the plain Developer Command Prompt, so the
linker was given 32-bit Windows libraries for a 64-bit game. A build with nothing to compile
still succeeds in that prompt, which is why it can seem fine until the first edit. Check the
prompt with echo %VSCMD_ARG_TGT_ARCH% as in
The wrong command prompt, then:
- The message says
library machine type 'x86' conflicts with target machine type 'x64'. The build folder is right and the prompt is wrong. Open the x64 Native Tools Command Prompt, go back to your project’s folder and build again. There is nothing to delete. - It says
library machine type 'x64' conflicts with target machine type 'x86'. The build folder was made in a 32-bit prompt, by a Labrador older than the check in A 32-bit prompt, and it keeps the 32-bit compiler: configuring again does not change it. In the x64 Native Tools Command Prompt, delete the build folder and configure and build again, as that entry shows.
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).
Application::load_manifest was called before Application::initialize().
Section titled “Application::load_manifest was called before Application::initialize().”main.cpp calls the three steps in the wrong order, or the app.initialize(); line is gone.
Application::run was called before Application::initialize(). is the same mistake met one
line later. The order is app.initialize(), then app.load_manifest(...), then app.run(...)
(The game).
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 game could not be loaded. when opened from file://
Section titled “The game could not be loaded. when opened from file://”The v0.3.0 starter has no loader-failure handler, so it stays at Loading... instead.
Double-clicking the generated HTML file is not enough. In Chrome, the minimal sample’s page
replaces Loading... with The game could not be loaded. Check your connection and reload the page., 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 34; Release lists 19 instead of 35. 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, and neither does a gamepad button: expect a player who uses
only a pad to hear nothing until the page has had a key, click or touch. 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 sounds from an XWB bank 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.
Texture ... has two files
Section titled “Texture ... has two files”A texture’s folder holds both name.dds and name.png, and the engine will not guess which one
is current. Delete the one you no longer use. The two paths in the message are where the game
looked, the folder beside the game, not game\content: the build copies new
files there but never removes old ones, so delete the old one in both places, for example:
del game\content\textures\hero.ddsdel out\build\x64-debug\game\textures\hero.ddsContent and the manifest says why the copy stays.
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, and for a texture it names both the .dds and the .png it would have read. 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.
The v0.3.0 engine reads only DDS textures and names just the .dds path. With that starter,
use texconv to make a DDS file. Keeping a PNG requires the newer engine.
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 or a sound bank’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 a sheet’s fields; a sound bank’s are waves, create_effect_instance_for_each_wave and
sound_effect_instances, and each effect instance’s name and wave.
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 sounds from an XWB bank) and build. On Windows the reader’s own
word, (WaveBank), follows the file name. In the browser build the same words begin the
reader’s own messages, such as the compact-entries one below. On Windows, ... is a streaming bank means xwbtool was run with -s; pack the bank again without it.
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).
Web Audio refuses a decoded wave
Section titled “Web Audio refuses a decoded wave”A browser buffer refusal names the bank and wave after Failed to open wave bank,
followed by the browser’s own reason. For a sample-rate refusal, export at
8,000 to 96,000 Hz and pack the XWB bank again
(Exporting sounds both platforms play).
The direct WAV and memory-bank routes reject rates outside that range before
asking Web Audio. A browser can also refuse a buffer because it cannot hold
the requested allocation; changing its sample rate is not a remedy for every
buffer error.
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.
The code execution cannot proceed because VCRUNTIME140D.dll was not found., or MSVCP140D.dll or ucrtbased.dll
Section titled “The code execution cannot proceed because VCRUNTIME140D.dll was not found., or MSVCP140D.dll or ucrtbased.dll”A file whose name ends in D before .dll, or ucrtbased.dll, is part of Microsoft’s debug
runtime. The friend was sent the debug build: MyGame.exe from out\build\x64-debug\game, or
that folder zipped. A debug build runs only on a PC with Visual Studio installed, and Microsoft
does not let you give its debug runtime away. Make the release build and send that, as
Send your game to a friend shows.
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).
Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.