[hoangchunghien]

What changes for the user

hflow doctor names the two most common reasons a recording will not open, instead of a blank or misleading message.

Input	Before	After
Empty (0-byte) file	not readable as MCAP:	not readable as MCAP: the file is empty (0 bytes)
Recording cut off mid-write (first half of a canonical episode)	not readable as MCAP: unknown (opcode 122) record has length 7707937301489634682 that exceeds limit 4294967296	not readable as MCAP: the file is truncated (it starts like an MCAP file but its end marker is missing, so the recording or copy may be incomplete): unknown (opcode 122) ...
Not an MCAP at all (an .mp4)	not readable as MCAP: not a valid MCAP file, invalid magic: ...	unchanged

Why

diagnose() formats the reader's exception text into the finding. mcap raises EndOfFile with an empty message for an empty file. For a truncated file, get_summary() reads the footer from wherever the file now ends, so the error describes arbitrary bytes. The existing no-summary finding already mentions truncation, but it only fires when the summary is cleanly absent, not when reading it raises.

Per the MCAP spec (references/mcap-spec.md, "Magic"), a complete file starts and ends with \x89MCAP0\r\n. When the read fails, the doctor now checks both ends: 0 bytes means empty, opening magic without closing magic means truncated. Otherwise it keeps the reader's message, and uses the exception type when that message is blank. The finding code stays unreadable, so automation that matches codes, and the existing per-file output shape, are unaffected. docs/FORMAT.md mentions the two cases next to the existing [error] unreadable: ... description.

Validation

New regression tests in tests/test_doctor.py: test_empty_file_is_reported_as_empty and test_truncated_file_is_reported_as_truncated (the latter truncates a synthesized canonical episode to half). Both failed on main at 43380ac with the messages in the table above.

uv sync --locked
uv run pytest -q tests/test_doctor.py          # 34 passed
uv run pytest -q -n 4                          # 2559 passed, 8 skipped
uv run ruff check --fix                        # All checks passed!
uv run ruff format                             # 322 files left unchanged
uv run ty check                                # All checks passed!
uv run hflow doctor empty.mcap truncated.mcap recording.mp4

Ubuntu 24.04, Python 3.13, ffmpeg 9.0.2.

I wrote this with help from an AI coding assistant, then reviewed and tested it myself.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[github-actions]

👋 Hi @hoangchunghien — thank you so much for your first contribution to HFlow!

A maintainer will review your pull request as soon as possible. In the meantime:

• ⭐ Star the repo: https://github.com/Hebbian-Robotics/hflow
• 💬 Join our Discord: https://discord.gg/vacepQvjmg
• 📖 Check CONTRIBUTING.md for the validation commands CI will run
• 📣 Share the project with your network

💡 Tip: one open pull request per contributor at a time. Before starting an issue, check its sidebar for an assignee or a linked pull request. Either one means somebody is already on it; everything else is fair game.

We are excited to have you here and appreciate your help making the project better! 🙌

[greptile-apps]

Confidence Score: 5/5

[Low impact] The PR appears safe to merge; both previous findings are fixed.

Summary

hflow doctor now explains empty and truncated recordings while keeping the unreadable finding code.

• hflow doctor names empty and cut-off MCAP files in unreadable findings.

_{Reviews (2) · Last reviewed commit: "fix(doctor): keep the unreadable finding..." · Reviewed by Greptile}

[hoangchunghien]

Both review points were right, fixed in 7330a91:

• A file holding only the opening magic (8 bytes) read the same bytes back as its end marker, so it was not named as truncated. The end check now needs room for both markers. There is a new test for a magic-only file and for magic plus 7 bytes.
• An OSError from the marker checks escaped diagnose. They now fall back to the reader's own message, so the rest of the batch still runs. There is a test with a stream whose seek raises.

tests/test_doctor.py has 37 passed, the full suite 2562 passed, and ruff and ty are clean.

[kstonekuan]

Thanks for the fix. Ruff, formatting, ty, the full suite (2562 passed, 8 skipped), and the Markdown link check passed. LGTM.