BabylonJS/Babylon.js · error · Error

Appropriate material adapter class not found

Error message

Appropriate material adapter class not found

What it means

_getOrCreateMaterialAdapter matches a loaded Babylon material against a list of registered adapter implementations (materialClass + adapterClass pairs). If the material's concrete class matches none of the registered implementations, the loop ends with `adapter` undefined and this error is thrown — the loader has no adapter capable of wrapping that material type.

Source

Thrown at packages/dev/loaders/src/glTF/2.0/glTFLoader.pure.ts:357

    /**
     * Creates or gets a cached material loading adapter with dynamic imports
     * @param material The material to adapt
     * @returns Promise that resolves to the appropriate adapter
     * @internal
     */
    public _getOrCreateMaterialAdapter(material: Material): IMaterialLoadingAdapter {
        let adapter = this._materialAdapterCache.get(material);
        if (!adapter) {
            const materialImpls = Array.from(this._pbrMaterialImpls.values());
            for (const impl of materialImpls) {
                if (material instanceof impl.materialClass) {
                    adapter = new impl.adapterClass(material);
                    break;
                }
            }
            if (!adapter) {
                throw new Error(`Appropriate material adapter class not found`);
            }
            const createdAdapter = adapter;
            this._materialAdapterCache.set(material, createdAdapter);
            this._materialAdapters.add(createdAdapter);
        }
        return adapter;
    }

    /** @internal */
    public dispose(): void {
        if (this._disposed) {
            return;
        }

        this._disposed = true;

        this._completePromises.length = 0;

View on GitHub (pinned to 0592b347b8)

Solutions

1. Ensure the module registering the needed material adapter implementation is imported (not tree-shaken away)
2. Upgrade/align Babylon.js packages so loader and material classes match versions
3. Check what material class triggered it (inspect the material) and whether a plugin should provide its adapter
4. If you ship a custom material, register an adapter implementation for it before loading

Example fix

// before
import { GLTFLoader } from "core/Loaders/glTF"; // adapter implementations never registered
const adapter = loader._getOrCreateMaterialAdapter(customMaterial); // throws
// after
import "core/Loaders/glTF/2.0/glTFMaterialAdapter"; // registers PBR/Standard material adapters
const adapter = loader._getOrCreateMaterialAdapter(pbrMaterial);

import "core/Loaders/glTF/2.0/..."; // ensure adapter-registration modules are side-effect imported before loading
if (!(material instanceof PBRMaterial) && !(material instanceof StandardMaterial)) {
    console.warn("Material class has no registered glTF adapter:", material?.getClassName?.());
}

function hasMaterialAdapter(material: unknown): material is PBRMaterial | StandardMaterial {
    return material instanceof PBRMaterial || material instanceof StandardMaterial;
}

try {
    const adapter = loader._getOrCreateMaterialAdapter(material);
} catch (e) {
    if (String(e.message).includes("Appropriate material adapter class not found")) {
        console.error(`No adapter for material class ${material.getClassName()}; check imports/plugin registration`);
    } else throw e;
}

When it happens

Trigger: A material created during glTF loading (e.g. PBRMaterial, StandardMaterial, or a material produced by another extension/plugin) whose class is not in the loader's material adapter registry; custom Material subclasses reaching the adapter path.

Common situations: Using a Babylon build where an adapter implementation isn't registered (missing/failed plugin, tree-shaken module); a third-party material class flowing into the glTF adapter cache; version mismatch between loader and material classes.

Related errors

• ${extraContext}: Material type not supported
• No PBR material implementation loaded
• Buffer access is out of range
• ${extensionContext}: Invalid area light type (${light.type})
• ${context}: Irradiance coefficients are missing

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