What does 'Composition HTML is empty or could not be parsed' mean in HyperFrames?

index.html mounts a scene with data-composition-src="compositions/scene-title.html", and that file is empty, contains no markup, or does not exist. HyperFrames cannot inline it.

Why it keeps happening

Almost always, an agent wrote the host reference first and the scene file second, and the second step never finished: a scene worker errored or was interrupted mid-write. The dominant filename in the failing renders was scene-title.html. The reference looked fine to index.html, so nothing complained until render.

The two error strings

They are the same problem at different levels of politeness.

• Composition HTML is empty or could not be parsed: <path> is the original message, from a guard added in June 2026. It names the file. The render pre-flight now lists every offending file at once.
• Cannot destructure property 'firstElementChild' of 'documentElement' as it is null. is the cryptic one. The HTML parser the CLI installs returns a document whose documentElement is null for empty or non-HTML input, and the inliner dereferenced it. It started appearing after a render pipeline change in 0.6.73, and was at one point described as the most common render failure in recent reports. It now surfaces as a typed, named error instead of a raw crash.

What older versions did, which matters if you are not on the latest

There was a stretch where empty scene files were deliberately skipped, so authoring could continue on partial projects. The cost was that a final render could silently drop a scene: it "succeeded", took about 93 seconds, and the scene was just not in the video. validate agreed that everything was fine.

If you have a video that is mysteriously missing a scene, this is the first thing to check, and the fix below applies to old and new versions alike.

Fix

1. Find the empty file. On a current version the error names it. On an older one, look at every data-composition-src in index.html and open each target.
2. Regenerate or rewrite the scene file, then confirm it contains real markup, not just whitespace.
3. If an agent produced the scene, re-run that scene's step rather than patching around it.

npx hyperframes lint

lint reports missing_or_empty_sub_composition with the file path.

Check it worked

npx hyperframes render --quality draft --output review.mp4

A healthy project starts rendering promptly. If the render sits for 45 to 90 seconds with no progress before finishing, something else is waiting on a timeline. See why every render takes 45 seconds longer than it should.

If you are building the tooling

Preview and Studio still tolerate a partial scene file (skip and continue), because mid-authoring iteration has to keep working. Only render refuses. If you assemble projects programmatically, validate scene content at the point you write it rather than at render.