# Troubleshooting

- Section: Documentation > Reference > Troubleshooting
- Canonical: https://covdbg.com/docs/reference/troubleshooting/

---

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 |
| `2` | No functions to track | Coverage filters excluded all functions |

---

## 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](/docs/reference/licensing-faq/) covers the personal repository slot and how to switch it at any time:

```powershell
# 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:

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

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

```powershell
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](/docs/reference/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:

```yaml
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:

```powershell
# 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:

```powershell
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:

```powershell
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:

```powershell
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):

```powershell
covdbg --log-level NONE --output "results.covdb" "tests.exe"
```

---

## Getting Help

If your issue isn't listed here:

1. Check the [CLI Reference](/docs/reference/cli-reference/) for correct usage
2. Review the [Configuration Reference](/docs/reference/configuration/) for filter syntax
3. Visit [covdbg.com/support](/resources/support/) for FAQs and resources
4. Contact [our support team](/company/contact/#email-addresses)