coverage "Couldn't parse '.coverage'" on combine in CI

By Kaveh Alemi·Latchkey

During coverage combine, coverage opened a per-shard .coverage.* data file it could not parse - it was empty, truncated, or written by a different coverage version - so the merge aborts.

What this error means

The combine step fails with "Couldn't parse data from '.coverage.runner.1234'" or "data file is not a database," usually after merging artifacts from parallel jobs.

coverage.exceptions.DataError: Couldn't parse data from '.coverage.host.4821.xz'
No source for code, or data file is not a valid SQLite database

Diagnose it: which interpreter and which environment?

which -a python python3 pip
python -c "import sys; print(sys.executable); print(sys.version)"
python -c "import sys; [print(p) for p in sys.path]"
pip list 2>/dev/null | head -20

Common causes

Mismatched coverage versions across shards

Shards that produced the data files ran different coverage versions; the on-disk format differs and combine cannot read them.

A truncated or empty data file

A shard that crashed or wrote nothing leaves a zero-byte or partial .coverage.* file that fails to parse.

How to fix it

Pin one coverage version everywhere

1. Pin the same coverage version across all shard jobs and the combine job.
2. Re-run so every data file uses one format.
3. Combine again.

pip install "coverage[toml]==7.5.4"
coverage combine
coverage report

Skip unparseable files defensively

Drop empty/corrupt data files before combining so one bad shard does not fail the merge.

# remove zero-byte data files before combine
find . -name '.coverage.*' -size 0 -delete
coverage combine

How to prevent it

• Pin a single coverage version across all jobs that read/write data files.
• Name parallel data files uniquely and upload them as artifacts cleanly.
• Validate shard artifacts are non-empty before combining.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation