BabylonJS/Babylon.js · error · Error

HIERARCHY expected

Error message

HIERARCHY expected

What it means

ReadBvh expects the very first non-empty line of a BVH file to be the keyword "HIERARCHY" (case-insensitive). If the first line is missing or is anything else, the file is not recognized as BVH and this error is thrown before any node parsing begins.

Source

Thrown at packages/dev/loaders/src/BVH/bvhLoader.ts:341

 * @returns The skeleton
 */
export function ReadBvh(text: string, scene: Scene, assetContainer: Nullable<AssetContainer>, loadingOptions: BVHLoadingOptions): Skeleton {
    const lines = text.split("\n");

    const { loopMode } = loadingOptions;

    scene._blockEntityCollection = !!assetContainer;
    const skeleton = new Skeleton("", "", scene);
    skeleton._parentContainer = assetContainer;
    scene._blockEntityCollection = false;

    const context = new LoaderContext(skeleton);
    context.loopMode = loopMode;

    // read model structure
    const firstLine = lines.shift();
    if (!firstLine || firstLine.trim().toUpperCase() !== _HierarchyNode) {
        throw new Error("HIERARCHY expected");
    }

    const nodeLine = lines.shift();
    if (!nodeLine) {
        throw new Error("Unexpected end of file after HIERARCHY");
    }
    const root = ReadNode(lines, nodeLine.trim(), null, context);

    // read motion data
    const motionLine = lines.shift();
    if (!motionLine || motionLine.trim().toUpperCase() !== _MotionNode) {
        throw new Error("MOTION expected");
    }

    const framesLine = lines.shift();
    if (!framesLine) {
        throw new Error("Unexpected end of file before frame count");
    }

View on GitHub (pinned to 0592b347b8)

Solutions

1. Open the file and confirm the first line is exactly "HIERARCHY" — remove any preamble (BOM, comments, HTML) before it or re-export the file.
2. Verify you are actually loading a BVH file; if the asset is another format, use the correct loader for it.
3. Re-download the file — a saved HTML error page or empty file will fail here.
4. Strip a UTF-8 BOM from the text before calling the loader if the source tool writes one.

Example fix

// before
const text = await (await fetch(url)).text(); // may start with BOM
skeleton = ReadBvh(text, scene, null, options);
// after
const text = (await (await fetch(url)).text()).replace(/^\uFEFF/, "").trimStart();
if (!text.toUpperCase().startsWith("HIERARCHY")) throw new Error("Not a BVH file");
skeleton = ReadBvh(text, scene, null, options);

function loadBvhSafely(raw: string): string {
  const text = raw.replace(/^\uFEFF/, "").trimStart();
  if (!text.toUpperCase().startsWith("HIERARCHY")) {
    throw new Error("Not a BVH file: expected HIERARCHY header.");
  }
  return text;
}
// then: ReadBvh(loadBvhSafely(rawText), scene, null, options);

function isBvhText(text: string): boolean {
  return text.replace(/^\uFEFF/, "").trimStart().toUpperCase().startsWith("HIERARCHY");
}

try {
  const skeleton = ReadBvh(text, scene, null, options);
} catch (e) {
  if (e instanceof Error && e.message === "HIERARCHY expected") {
    console.error("This file is not a valid BVH file (missing HIERARCHY header).");
  } else { throw e; }
}

When it happens

Trigger: Passing a non-BVH file (FBX/glTF/JSON/XML, or an image) to the BVH loader; passing a file that starts with a BOM, comment, blank leading lines handled differently, or a motion-only snippet without its HIERARCHY header; file content arriving URL-encoded or base64-wrapped.

Common situations: Wrong file extension/asset type wired into the loader pipeline; download managers saving an HTML error page as .bvh; export tools writing a preamble comment before HIERARCHY; stripping the header when extracting only frame data.

Related errors

• Expected opening { after type & name
• Expected OFFSET, but got:
• Expected CHANNELS definition
• Unexpected end of file: missing OFFSET
• OFFSET: Invalid number of values

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/9fb40df44c30d28d. Report an issue: GitHub.