Troubleshooting

Solutions to common issues when using covdbg.

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 sign-in or a project token, public repositories included; they are free, but for somebody.

Fix: Sign in, or give CI a project token. 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"

Missing PDBs (no debug symbols)

Symptom: covdbg runs, but nothing shows up in exports (or very little data)

Fix:

1. Build with debug symbols enabled (MSVC /Zi compiler flag + /DEBUG linker flag)
2. Ensure .pdb files are in the same directory as your binaries
3. For CMake: use CMAKE_BUILD_TYPE=Debug or RelWithDebInfo

---

Exit code 2: No functions to track

Symptom: covdbg exits with code 2 and message "No functions passed the coverage filter"

Cause: Your .covdbg.yaml filters exclude all functions

Fix:

1. Check your include/exclude patterns in .covdbg.yaml
2. Start with broader includes:

version: 1
coverage:
  default:
    files:
      include:
        - "**/*.cpp"
        - "**/*.h"

3. Run with debug logging to see what's being filtered:

covdbg --log-level DEBUG --output "results.covdb" "tests.exe"

---

Source files are missing from the export

Filters exclude your code

Symptom: Expected source files don't appear in LCOV/GCOV exports

Fix:

1. Review your .covdbg.yaml include/exclude patterns
2. Try without any config file first to see all captured data
3. Start with a broad include, then narrow down

See Configuration.

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/**"

---

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\"

---

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:

1. Check the CLI Reference for correct usage
2. Review the Configuration Reference for filter syntax
3. Visit covdbg.com/support for FAQs and resources
4. Contact our support team