An .mcap file is sitting on your disk, PlotJuggler is supposed to read MCAP — and it will not open. Of all the file problems on this site, this is the one where which PlotJuggler line you are running decides everything, because PJ3 and PJ4 reach MCAP by genuinely different routes. This guide separates the causes: wrong route for your line, a recording whose structure needs its ROS context, and a genuinely damaged file — including the one hopeful fact in this area, that PJ4 specifically improved reading of corrupted MCAP files. It belongs to the Troubleshooting hub; the happy-path workflow is in the ROS bag and MCAP tutorial.
Cause 1 — You are on PJ3 without the MCAP plugin set
In the PJ3 world, rosbag2 and MCAP support lives in the ROS 2 / MCAP plugin set — the separate plotjuggler-ros-plugins package — not in a standalone PJ3 binary. A PJ3 install without that package has no MCAP loader, and the file will be refused for the reason explained in missing data loaders explained. The documented install is sudo apt install ros-$ROS_DISTRO-plotjuggler-ros, launched with ros2 run plotjuggler plotjuggler; if the plugin layer itself is in question, work through ROS 2 plugin not loading first. This failure class is well attested on the project tracker, under titles such as “cannot open mcap bags” (issue #783) and “Error reading the mcap file” (issue #754) — real reports, with real files, that mostly resolve into route and environment questions.
Cause 2 — You expected PJ3 behaviour from PJ4, or the reverse
PlotJuggler 4 reads MCAP natively. MCAP is on PJ4’s own file list, alongside CSV, Parquet, PX4 ULog, LeRobot, MP4, PCD and PLY — no ROS installation is required for the file itself. So the diagnostic fork is sharp: if a plain .mcap will not open in PJ4, the plugin-route explanation does not apply, and you should look at the file itself (causes 3 and 4 below) and at whether your PJ4 build is current — 4.0.0 from the Download page. Conversely, if it opens in PJ4 and not in your PJ3, nothing is broken: the generations differ here by design. One tracker report captures a subtler version of this — “Having trouble opening an mcap file created on Linux in PlotJuggler for Windows?” (issue #958, still open) — a reminder that where a file was written, and with what message definitions, can matter as much as where it is read.
Cause 3 — The recording needs its message context
An MCAP file is a container of timestamped, topic-structured messages, and reading it means understanding the messages inside it. Phrase this carefully, because it is where folklore grows: a rosbag2 recording carries a storage identifier — the recording’s metadata names which storage implementation wrote it (MCAP being one of them) — and readers use that recorded structure to interpret the data. When a recording was written with custom message types, the reading side needs those message definitions available; a reader that lacks them can fail on a file that is perfectly intact. In practice: if the file came from a ROS 2 system with custom messages, open it in an environment that has those definitions — typically the ROS route, on the machine (or a machine configured like the one) that recorded it. If the same file opens on the recording machine and nowhere else, this is almost certainly your cause, and it is an environment fix, not a file repair.
Cause 4 — The file is actually damaged
Recordings get truncated — a recorder killed mid-write, a copy interrupted, a disk that filled up. Here the version history genuinely helps you: during the PJ4 preview cycle, 3.999.9 (10 August 2026) specifically added improved reading of corrupted MCAP files, and that capability shipped in the 4.0 line. So the practical advice is concrete: a damaged MCAP that a strict reader rejects is worth one attempt in a current PJ4 before you declare it lost. Keep expectations honest — “attempt” is the project’s own framing, not a promise of recovery — and work on a copy of the file, never the only original. If PJ4 recovers the data, export or re-save what you need immediately (PJ4 can export to CSV and Arrow-Parquet) rather than trusting the damaged container for future sessions.
A diagnostic order that respects all four causes
- State your line out loud: PJ4 (native MCAP) or PJ3 (plugin route)? Half of all MCAP confusion dies here.
- On PJ3: confirm the ROS plugins package is installed for your distribution and launch via
ros2 run. - Test a second, known-good MCAP if you can get one. If it opens, your install is healthy and the problem is this specific file.
- Ask where the file was recorded and whether custom messages were involved; if so, reproduce that message environment.
- Suspect damage only after the route checks — then try the file, as a copy, in current PJ4 for its corrupted-file reading.
For the normal opening workflow once it works, see the ROS bag and MCAP tutorial and the Tutorials hub. Other symptoms are indexed on the Troubleshooting hub.