Troubleshooting C++ Coverage on Windows
Solutions to common issues when using covdbg.
Exit Codes
| Code | Meaning | Common Cause |
|---|---|---|
0 |
Success | Everything worked correctly |
1 |
General error | Process creation failed, invalid arguments, license issues, covdbg.exe and its agent DLLs from different builds, an agent DLL missing beside covdbg.exe, a program of another architecture, a database written by a covdbg with another schema version, a path that names a device such as NUL, an unexpected error |
2 |
Nothing measured | Coverage filters excluded all functions, or modules left the executable out; the program still ran (from covdbg 1.5.1) |
covdbg's exit code is its own, not the program's: a failing or crashing test run that covdbg measured still exits 0. covdbg prints how the program exited below its output. To have a CI step fail when the tests fail, add --propagate-exit-code (from covdbg 1.5.1); see Exit Codes.
No coverage output (.covdb not created)
Not signed in
Symptom: This run is not licensed: Not signed in and no .covdb file. Every run carries a credential: your sign-in, a project token, or, on GitHub Actions, the job's own workflow token. Public repositories are free, but for somebody.
Fix: Sign in, or give CI a project token. A public repository on GitHub Actions needs neither: grant the job id-token: write (see GitHub Actions). GitHub issues no workflow token to a pull request from a fork, so such a run is refused. The Licensing FAQ covers the personal repository slot and how to switch it at any time:
# Developers: sign in once with GitHub
covdbg login
# CI: a project token instead of a sign-in
$env:COVDBG_PROJECT_TOKEN = "<your-project-token>"
# Then run
covdbg --output "results.covdb" "tests.exe"
Sign-in no longer valid
Symptom: This run is not licensed: Your covdbg sign-in is no longer valid. Run `covdbg login` to sign in again. The session was ended on your profile at app.covdbg.com, or it expired. In CI the message reads The license service rejected COVDBG_PROJECT_TOKEN instead.
Fix: Run covdbg login again. In CI, check that COVDBG_PROJECT_TOKEN holds a current token from the team's page at app.covdbg.com.
Signed in for a team without a seat
Symptom: This run is not licensed: followed by the service's explanation, naming your account and the team. A sign-in is for one team, and you hold no seat in the team this machine is signed in for.
Fix: Check the team with covdbg whoami. Sign in for a team where you hold a seat, or for personal use:
covdbg login --team <slug>
covdbg login --team personal
A config in a subfolder of a checkout is refused
Symptom: before covdbg 1.5.1, signed in for personal use, a run with a .covdbg.yaml in a subfolder of a public checkout (source_root: ".") is refused with This run is not licensed: Your personal use of covdbg is locked to the repository with root commit ..., while the same run with the config at the checkout's root is licensed. The log (.covdbg\Logs\covdbg.log) shows No git remote in <the subfolder> and Checking entitlement: repository=(none).
Cause: covdbg before 1.5.1 read the git remote only from the source root directory itself, and did not walk up to the checkout's root. The run named no remote, so it was decided as a private repository without one.
Fix: update to covdbg 1.5.1, which names the checkout around the source root wherever the config sits in it; the log then shows Naming the git work tree at <checkout root>, around the source root <the subfolder>. On an earlier version, put the .covdbg.yaml at the checkout's root and include the subfolder from there:
version: 1
source_root: "."
coverage:
default:
files:
include:
- "native/**"
The Licensing FAQ says which repository a run is licensed for.
Missing PDBs (no debug symbols)
Symptom: covdbg runs, but nothing shows up in exports (or very little data)
Fix:
- Build with debug symbols enabled (MSVC
/Zicompiler flag +/DEBUGlinker flag) - Ensure
.pdbfiles are in the same directory as your binaries - For CMake: use
CMAKE_BUILD_TYPE=DebugorRelWithDebInfo
Exit code 2: Nothing was measured
Symptom: covdbg exits with code 2 and prints covdbg: nothing was measured: no function of tests.exe passes the coverage filter of .covdbg.yaml, or tests.exe has no debug information covdbg can read or analyse (see the log), or tests.exe is not selected under modules: in .covdbg.yaml. From covdbg 1.5.1 the program still ran, unmeasured, and the database covdbg wrote is empty; with --propagate-exit-code covdbg exits with the program's exit code instead of 2. Before 1.5.1 the program did not run, and the message was "No functions passed the coverage filter".
Cause: Your .covdbg.yaml filters exclude all functions, the program has no PDB covdbg can read, or modules does not select the executable
Fix:
- Check your include/exclude patterns in
.covdbg.yaml - Start with broader includes:
version: 1
coverage:
default:
files:
include:
- "**/*.cpp"
- "**/*.h"
- Run with debug logging to see what's being filtered:
covdbg --log-level DEBUG --output "results.covdb" "tests.exe"
- If the code you want to measure lives in a DLL the executable loads, select that DLL under
modules(see the next section). With libraries selected, an executable with nothing of its own to measure is no longer an error. - If the reason is
tests.exe is not selected under modules:, see My executable is no longer measured. - If the target is a launcher without symbols that starts the real work, such as
ctest.exeorcmd.exe, add--follow-children. covdbg then runs the launcher unmeasured and measures the processes it starts:
covdbg --follow-children --output "tests.covdb" ctest.exe --test-dir build
Code in a DLL is missing from the report
Symptom: Functions from a library your tests call never appear in the database, not even as uncovered.
Cause: covdbg measures only the executable it launches unless shared libraries are selected. Code in a DLL runs, but is not measured.
Fix: Select the library under modules and make sure its source files pass files:
coverage:
default:
files:
include:
- "src/**"
modules:
include:
- "mylib.dll"
From covdbg 1.5.1, this measures the library alone. To measure the executable too, add its name under include; see My executable is no longer measured.
If covdbg says "nothing was measured" and exits with code 2 (code 1 before covdbg 1.5.1), the executable had nothing of its own to measure and no selected library with functions to track was loaded. Check that the modules pattern matches the DLL's file name or path, that its PDB sits beside it, and that its sources are included. See Shared Library Patterns.
My executable is no longer measured
Symptom: From covdbg 1.5.1, the executable's own source files, or those of a followed child process, are missing from the report, while the libraries selected under modules are there. The log says 'tests.exe' (1234) is not selected under modules:. When nothing else was measured either, covdbg exits with code 2 and prints covdbg: nothing was measured: tests.exe is not selected under modules: in .covdbg.yaml.
Cause: with modules: include:, an executable is a module like the libraries and is measured only when a pattern selects it. A list of libraries alone, such as "*.dll" or "mylib.dll", measures those libraries and not the program that loads them, as OpenCppCoverage's --modules mylib.dll does. A modules: exclude: pattern that matches the executable leaves it out too. Before 1.5.1, the executable was always measured beside the selected libraries.
Fix: add the executable's name to modules: include:, and take it out of modules: exclude::
coverage:
default:
modules:
include:
- "*.dll"
- "tests.exe"
Leave it out when you want the library's coverage alone, for example when the test runner compiles in sources the library has too: their lines and hits are then the library's only. An executable left out still runs, its libraries are measured, and with --follow-children its children are followed. See Shared Library Patterns.
A targets: entry's settings don't apply
Symptom: the settings of a targets: entry in .covdbg.yaml, such as settings: follow_children: true or its own files patterns, have no effect on the program they name. Or covdbg prints, on stderr and in the log:
Warning: targets: entries 'My_Tests.exe' and 'my_tests.exe' differ only in case and name the same program; covdbg uses the first, 'My_Tests.exe'
Cause: target: is matched against the program's file name, without a directory. From covdbg 1.5.1 it is compared as Windows compares file names, without regard to case, so My_Tests.exe and my_tests.exe name the same program. Of two entries that differ only in case, or are the same, the first one in the file counts, all of it, and the settings of the other are not read. A repeated entry gets Warning: targets: names 'my_tests.exe' twice; covdbg uses the first entry. Before 1.5.1 the name had to match in case too, so target: "my_tests.exe" did not apply to a program started as My_Tests.exe.
Fix: keep one entry per program and put all of its settings there. On covdbg 1.5.0 or earlier, spell target: in the case of the program's name as covdbg starts it. See Target Matching.
A test passes under covdbg but crashes on its own
Symptom: a test passes under covdbg, but run on its own it ends with exit code 0x80000003 (-2147483645). covdbg prints covdbg: continued past N breakpoint(s) the program did not handle below the program's output.
Cause: the program breaks into a debugger itself, with __debugbreak(), DebugBreak(), or an assertion helper that does, and none of its own handlers takes the breakpoint. From covdbg 1.5.1, covdbg continues past such a breakpoint, as OpenCppCoverage and Visual Studio's "Continue" do, so the code after it runs and is measured. Without a debugger, the program ends at the first one.
Fix: to have the program end there under covdbg too, pass --stop-on-break (or set COVDBG_STOP_ON_BREAK=1), and add --propagate-exit-code to fail the CI step with the program's status. A breakpoint the program handles itself always reaches its handler. See Breakpoints in the program.
Exit code 1: Stopped on an unexpected error
covdbg prints Stopped on an unexpected error: and the reason, and exits with code 1, when something fails that it has no message of its own for. The same line goes to the log when logging has started. Before covdbg 1.5.1, such an error ended covdbg without a message.
This is a bug in covdbg. Report it with the command line, the .covdbg.yaml and the log (see Check log files).
A path that goes through a Windows device name, such as C:\out\NUL or C:\out\NUL\run.covdb, names no file. From covdbg 1.5.1, covdbg refuses it as --config, --output, in baseline: or as the output of analyze, convert and merge, with an error and exit code 1.
Exit code 1: The agent did not start
Symptom: covdbg exits with code 1, and the output names a process with the message "the agent and covdbg.exe disagree on the shared-memory layout (agent vN, covdbg vM); the process ran un-instrumented", followed by "The agent did not start in N measured process(es)".
Cause: From covdbg 1.5.0, covdbg.exe checks that the agent it loads into the measured program (libcovdbg.dll, or libcovdbg32.dll for 32-bit programs) comes from the same build. Here it does not, usually because files from two installations or versions were mixed.
Fix: Reinstall covdbg, so that covdbg.exe, libcovdbg.dll and libcovdbg32.dll come from one build. The coverage database is still written, but it lacks the coverage of the processes the message names.
Exit code 1: Agent DLL not found
Symptom: covdbg exits with code 1 before the program under test runs, and prints:
Agent DLL not found: C:\Tools\covdbg\libcovdbg.dll. covdbg loads libcovdbg.dll into every native process it measures and looks for it beside covdbg.exe; reinstall covdbg, or put libcovdbg.dll there.
covdbg: the target was not run and no coverage database was written
For a 32-bit program the message names libcovdbg32.dll and "every 32-bit process" instead. No coverage database is written.
Cause: From covdbg 1.5.0, covdbg.exe checks for its agent before the program it measures runs any code. It looks only in its own folder: libcovdbg.dll for a native program, libcovdbg32.dll for a 32-bit one. The file is missing there, usually because covdbg.exe was copied somewhere on its own, or the DLL was removed. Before 1.5.0 the same situation ran the program, recorded nothing, and exited with code 0.
Fix: Reinstall covdbg, or put the DLL the message names back beside covdbg.exe. Keep covdbg.exe, libcovdbg.dll and libcovdbg32.dll together, as the installer and the ZIP archive lay them out (see Components).
If the agent is missing only for a child process covdbg follows, for example a 32-bit program started by a 64-bit test, the run goes on: the message is printed for that process, which runs un-instrumented, and the run ends with "The agent did not start in N measured process(es)" and exit code 1. The coverage database is still written, but it lacks that process's coverage.
Exit code 1: A program of another architecture is refused
Symptom: covdbg exits with code 1 before the program under test runs, and prints:
covdbg: 'tests.exe' is built for ARM64, and this covdbg is the x64 build, which measures x64 and 32-bit x86 programs. Use the covdbg build for the program's architecture.
The ARM64 build, given a 32-bit program, says this covdbg is the ARM64 build, which measures ARM64 programs only. Use the x64 covdbg build, which measures 32-bit programs too. No coverage database is written.
Cause: From covdbg 1.5.0 there is one covdbg build per architecture. The x64 build measures x64 and 32-bit x86 programs, the ARM64 build ARM64 programs. An image built for ARM64EC is measured by neither.
Fix: Install the build for the program's architecture; see Windows on ARM. In GitHub Actions, liasoft/setup-covdbg installs the build for the runner's architecture: run ARM64 tests on an ARM64 runner such as windows-11-arm, see Windows on ARM runners.
A followed child process of another architecture is not refused: it runs un-instrumented, the log says 'tool.exe' (1234) is built for x64; this ARM64 covdbg runs it un-instrumented., and the run goes on.
Source files are missing from the export
Filters exclude your code
Symptom: Expected source files don't appear in LCOV/GCOV exports
Fix:
- Review your
.covdbg.yamlinclude/exclude patterns - Try without any config file first to see all captured data
- Start with a broad include, then narrow down
See Configuration.
Assembly files are missing
Symptom: .asm files, such as those of a statically linked OpenSSL, are missing from the report, executed or not
Cause: Before covdbg 1.5.1, code outside a procedure was not measured: all code NASM assembles, and MASM's outside PROC ... ENDP
Fix: Update to covdbg 1.5.1, and check that your files: filters include the .asm files. See Assembly Outside Procedures.
Source paths don't match your machine
Symptom: Exports contain unexpected absolute paths or paths from another machine
Fix: Set source_root in .covdbg.yaml to normalize paths:
version: 1
source_root: "." # Paths relative to config file location
coverage:
default:
files:
include:
- "src/**"
Lines are missing from the report
Marker comments or exclude_lines leave them out
Symptom: lines of a source, or whole functions, are not in the report at all, not even as lines that did not run. Often every line from some point to the end of a file is missing. covdbg may print a line such as:
covdbg: D:\src\parse.cpp: LCOV_EXCL_START on line 40 has no stop marker; the lines to the end of the file are excluded
Cause: from covdbg 1.5.1, the marker comments of lcov and gcovr (LCOV_EXCL_LINE, LCOV_EXCL_START ... LCOV_EXCL_STOP, the same with GCOVR_ and GCOV_, LCOV_UNREACHABLE_* and GCOVR_EXCL_FUNCTION) exclude lines without any configuration, and so do the exclude_lines patterns of the configuration. A start marker without its stop marker excludes every line to the end of its file, as in lcov. covdbg 1.5.0 read no markers, so a project that has them for lcov or gcovr sees those lines leave its reports.
Fix: add or correct the marker covdbg names. To see whether the markers are the cause at all, set exclusion_markers: false in coverage.default and compare the reports. An exclude_lines pattern must match the whole line, so '\s*\}.*' excludes every line that starts with a closing brace. See Excluding Lines.
"a line marked unreachable ran"
Symptom: covdbg prints covdbg: D:\src\parse.cpp:23: a line marked unreachable ran after the run.
Cause: the line has an LCOV_UNREACHABLE_LINE marker, or is in an LCOV_UNREACHABLE_START region, and it ran. The marker is in the wrong place, or the code is reachable after all. lcov reports the same as an unreachable error.
Fix: move the marker to the code that cannot run, or handle the case the code reaches. The line stays excluded either way, and the message does not change covdbg's exit code. A region marker on the line of an if marks the condition, which runs whenever the if does: put the start marker inside the block. See Marker Comments.
convert fails
LCOV convert fails
Symptom: covdbg convert --format LCOV fails
Common causes:
- Output path is a directory instead of a file
- Parent directory doesn't exist
Fix: Ensure output is a file path with existing parent directory:
# Correct: file path
covdbg convert --input "results.covdb" --format LCOV --output "coverage.lcov"
# Wrong: directory path
covdbg convert --input "results.covdb" --format LCOV --output "coverage\"
GCOV convert fails
Symptom: covdbg convert --format GCOV fails
Common causes:
- Output directory doesn't exist
- Output path is a file instead of a directory
Fix: Create the output directory first:
New-Item -ItemType Directory -Force -Path "gcov-output"
covdbg convert --input "results.covdb" --format GCOV --output "gcov-output\"
A database of another covdbg version is refused
Symptom: covdbg convert or covdbg merge exits 1, or the MCP server's open_coverage fails, with:
Database schema version 8 is older than this build supports (9), and no migration exists. Regenerate the coverage database with this version of covdbg.
Cause: covdbg 1.5.1 writes version 9 of the coverage database, and the database was written by covdbg 1.5.0 or earlier. There is no migration.
Fix: Record the coverage again with covdbg 1.5.1. The message Database schema version 9 is newer than this build supports (8) is the opposite case: covdbg 1.5.0 or earlier reads a database written by covdbg 1.5.1. Update covdbg on that machine, for example on the CI runner that merges or converts the databases. See Databases from Earlier Versions.
Debugging Tips
Enable verbose logging
Use --log-level DEBUG or --log-level TRACE for detailed output:
covdbg --log-level DEBUG --output "results.covdb" "tests.exe"
Check log files
covdbg writes detailed logs (DEBUG level and above) to its .covdbg directory:
Default location: .covdbg\Logs\covdbg.log in the working directory covdbg was started from
Log files rotate automatically (up to 5 files, 15MB each).
To use a custom log file:
covdbg --log-file "C:\path\to\debug.log" --output "results.covdb" "tests.exe"
Silent mode for CI
If you only want to see your test output (no covdbg messages):
covdbg --log-level NONE --output "results.covdb" "tests.exe"
Getting Help
If your issue isn't listed here:
- Check the CLI Reference for correct usage
- Review the Configuration Reference for filter syntax
- Visit covdbg.com/support for FAQs and resources
- Contact our support team