Troubleshooting

Solutions to common issues when using covdbg.

Exit Codes

CodeMeaningCommon Cause
0SuccessEverything worked correctly
1General errorProcess creation failed, invalid arguments, license issues
2No functions to trackCoverage filters excluded all functions

No coverage output (.covdb not created)

License is missing

Symptom: covdbg exits early and no .covdb file is produced, or a message about “evaluation mode”

Fix: Set your license before running covdbg:

# Option A: Direct token
$env:COVDBG_LICENSE = "<your-jwt>"

# Option B: License file path
$env:COVDBG_LICENSE_FILE = "C:\path\to\license.jwt"

# Then run
covdbg --output "results.covdb" "tests.exe"Code language: PowerShell (powershell)

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"Code language: YAML (yaml)
  1. Run with debug logging to see what’s being filtered:
covdbg --log-level DEBUG --output "results.covdb" "tests.exe"Code language: PowerShell (powershell)

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/**"Code language: YAML (yaml)

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\"Code language: PowerShell (powershell)

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\"Code language: PowerShell (powershell)

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"Code language: PowerShell (powershell)

Check log files

covdbg writes detailed logs (DEBUG level and above) to the application data directory:

Default location: %APPDATA%\Liasoft\covdbg\Logs\covdbg.log

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"Code language: PowerShell (powershell)

To use a custom application data directory:

covdbg --appdata "C:\custom\covdbg" --output "results.covdb" "tests.exe"Code language: PowerShell (powershell)

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"Code language: PowerShell (powershell)

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 support@covdbg.com