BabylonScenePathToObjectConverter: unknown collection "${col

Error message

BabylonScenePathToObjectConverter: unknown collection "${collectionName}" in path "${path}".

What it means

The first path segment after the Babylon prefix is treated as a collection name (e.g. transformNodes, meshes) and looked up in the converter's registered object tree. If no collection with that name exists, the library throws rather than returning undefined, because an unknown collection would silently break instance and property resolution downstream.

Source

Thrown at packages/dev/loaders/src/glTF/2.0/Extensions/babylonScenePathToObjectConverter.ts:142

     * @returns an object-info container holding the resolved instance and accessor
     */
    public convert(path: string): IObjectInfo<IObjectAccessor> {
        if (!path.startsWith(BABYLON_SCENE_OBJECT_MODEL_PREFIX)) {
            throw new Error(`BabylonScenePathToObjectConverter: path "${path}" does not start with the expected prefix "${BABYLON_SCENE_OBJECT_MODEL_PREFIX}".`);
        }

        // Strip the namespace prefix and split. Ignore trailing empty segments
        // so refs of the form "/extensions/BABYLON_scene_objects/transformNodes/42/" parse cleanly.
        const tail = path.slice(BABYLON_SCENE_OBJECT_MODEL_PREFIX.length);
        const parts = tail.split("/").filter((p) => p.length > 0);
        if (parts.length === 0) {
            throw new Error(`BabylonScenePathToObjectConverter: path "${path}" is missing a collection name.`);
        }

        const collectionName = parts[0];
        const collection = (this._tree as unknown as Record<string, IBabylonObjectCollection<any> | undefined>)[collectionName];
        if (!collection) {
            throw new Error(`BabylonScenePathToObjectConverter: unknown collection "${collectionName}" in path "${path}".`);
        }

        // Handle `<collection>.length` (no instance lookup).
        if (parts.length === 2 && parts[1] === "length") {
            const arr = this._getCollectionArray(collectionName);
            return { object: arr, info: collection.length as AnyAccessor };
        }

        if (parts.length < 2) {
            throw new Error(`BabylonScenePathToObjectConverter: path "${path}" is missing an instance id.`);
        }

        // parseInt would accept "12abc" as 12; require an all-digits id so a malformed path fails
        // loudly instead of binding to the wrong instance.
        if (!/^\d+$/.test(parts[1])) {
            throw new Error(`BabylonScenePathToObjectConverter: invalid uniqueId "${parts[1]}" in path "${path}".`);
        }
        const uniqueId = parseInt(parts[1], 10);

View on GitHub (pinned to 0592b347b8)

Solutions

Use one of the collection names registered by the extension (check the tree/registration code for the exact names, which are case-sensitive).
Fix casing/typos in the first path segment (e.g. "transformNodes" not "transformnodes").
If the collection genuinely should exist, ensure the extension that registers it ran before convert() is called.

Example fix

// before
converter.convert(`${prefix}bones/7/position`); // "bones" not registered
// after
converter.convert(`${prefix}transformNodes/7/position`);

Defensive patterns

Strategy: validation

Validate before calling

const KNOWN = new Set(["transformNodes", "meshes"]); // match the registered tree
const collection = path.slice(BABYLON_SCENE_OBJECT_MODEL_PREFIX.length).split("/")[0];
if (!KNOWN.has(collection)) {
  throw new Error(`Unknown collection: ${collection}`);
}
converter.convert(path);

Type guard

function isKnownCollection(path: string, known: ReadonlySet<string>): boolean {
  const first = path.slice(BABYLON_SCENE_OBJECT_MODEL_PREFIX.length).split("/").filter(Boolean)[0];
  return first !== undefined && known.has(first);
}

Try / catch

try {
  const info = converter.convert(path);
} catch (e) {
  // unknown collection; verify registered collection names and skip
}

Prevention

Keep a single source of truth (Set/enum) of registered collection names used by path builders
Remember names are case-sensitive; avoid hand-typing them
Confirm the extension that registers the collection has run before conversion

When it happens

Trigger: convert() called with a first segment that is not one of the collections registered in the tree, e.g. "/extensions/BABYLON_scene_objects/bones/7/position" when only transformNodes/meshes/etc. are registered, or a typo like "transformnodes" (wrong case).

Common situations: Typos or casing mistakes in hand-written pointers; referencing a collection type the host extension never registered (older runtime lacking that collection); assuming all Babylon scene types are exposed when only a subset is.

Related errors

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