CBECC does not fail politely. When a .ribd25 refuses to open, you may get a terse dialog, a partially loaded tree, or nothing at all. The first move, every time: open the .log file CBECC writes next to your project. It almost always names the exact object and property that broke, in far more detail than the error dialog. We have generated and debugged enough of these files to say the failures cluster into five families.
1. Dangling component references
Everything in a .ribd25 refers to everything else by name. A window belongs to a wall by naming it; an HVAC system points at coils and distribution by name. Delete or rename a component without chasing down everything that referenced it and you get an orphan: ResWin “W-103” — parent not found. Hand-edits are the classic cause, but any tool that assembles the file from parts can produce one if it removes a wall and forgets the windows that lived on it. The fix is mechanical — search the file for the stale name — but the lesson is structural: never delete a named object without grepping for its name first.
2. Invalid enum values
Many properties accept only an exact list of legal strings, and the legal lists change between code cycles. A value that reads perfectly sensibly to a human — a PVSizeOption of “Standard” where the 2025 ruleset expects a different token, a wall status or water-heater type carried over from .ribd22 vocabulary — is simply not in the 2025 enum, and CBECC stops. There is no fuzzy matching and no “did you mean.” The only reliable source of truth is what CBECC 2025 itself writes: build a small reference project in the GUI, save it, and read the tokens it emits.
3. Azimuth convention mistakes
Orientation errors are the sneakiest because the file often still opens — and then the analysis is quietly wrong, or fails validation later. Residential CBECC works with a front orientation for the building and surface azimuths that must respect the expected convention; feed it absolute compass bearings where it wants building-relative values, or a 405° that someone forgot to normalize into 0–360, and your south glass ends up facing a direction that does not exist. If a model passes suspiciously well or fails inexplicably, check orientation before anything else: rotate the front orientation 90° and see if the results move the way the real building would.
4. Openings bigger than their wall
Every window and door subtracts from its parent wall's gross area. Let the openings on a wall add up to more than the wall itself — a mis-scaled dimension, a double-counted slider that appears on two elevation views of the same corner, a wall drawn per-story but given single-story height — and the net area goes negative. CBECC objects, sometimes with a clear message, sometimes as a geometry failure two steps later. The sanity check is one division: openings over gross area, per wall, should land in believable territory. A wall at 95 percent glass is either a curtain wall or a bug, and on a wood-framed house it is a bug.
5. Missing sizing options
Some system objects require explicit sizing declarations — how equipment capacity is determined, how the PV is sized, which options apply — and the file is invalid without them. This bites generated files hardest: the GUI fills these fields with defaults as it creates objects, so a file written outside the GUI can omit a property no human ever consciously sets. The symptom is an analysis that errors on a system that looks completely normal in the tree. The cure, again, is comparing against a GUI-authored reference file to see which properties CBECC considers non-optional.
The pattern across all five: CBECC is strict because the compliance analysis has legal weight, and strictness beats guessing. Read the .log, keep a known-good reference file from the GUI, and treat every name, enum, and area as something that must reconcile. Boring habits, quiet plan checks.