BabylonJS/Babylon.js · error

Material "${material.name}" effect is not ready. Wait for it

Error message

Material "${material.name}" effect is not ready. Wait for it to be rendered.

What it means

This error is thrown by the inspector CLI `get-shader-code` command when the material's compiled Effect exists but its GPU program has not finished compiling/linking yet (effect.isReady() is false). Babylon.js compiles shaders asynchronously, so an effect can be non-null while still not ready to execute. The command refuses to return shader source until the pipeline is ready.

Source

Thrown at packages/dev/inspector-v2/src/services/cli/shaderCommandService.ts:49

                }

                const id = parseInt(args.uniqueId, 10);
                if (isNaN(id)) {
                    throw new Error("uniqueId must be a number.");
                }

                const material = scene.materials.find((m) => m.uniqueId === id);
                if (!material) {
                    throw new Error(`No material found with uniqueId ${id}.`);
                }

                const effect = material.getEffect();
                if (!effect) {
                    throw new Error(`Material "${material.name}" has no effect. It may not have been rendered yet.`);
                }

                if (!effect.isReady()) {
                    throw new Error(`Material "${material.name}" effect is not ready. Wait for it to be rendered.`);
                }

                const variant = args.variant ?? "compiled";

                let vertexShader: string;
                let fragmentShader: string;

                switch (variant) {
                    case "compiled":
                        vertexShader = effect.vertexSourceCode;
                        fragmentShader = effect.fragmentSourceCode;
                        break;
                    case "raw":
                        vertexShader = effect.rawVertexSourceCode;
                        fragmentShader = effect.rawFragmentSourceCode;
                        break;
                    case "beforeMigration":
                        vertexShader = effect.vertexSourceCodeBeforeMigration;

View on GitHub (pinned to 0592b347b8)

Solutions

  1. Render at least one frame with the material active, then retry the command
  2. Wait for readiness via scene.executeWhenReady() or the material's onCompiled callback / effect.getPipelineContext() readiness before calling get-shader-code
  3. Ensure the material is actually assigned to a mesh that is in the camera frustum / enabled so Babylon compiles its effect
  4. Check for shader compilation errors in the console (a failed compile leaves the effect never-ready); fix the shader or material configuration
  5. Use scene.whenReadyAsync() in headless flows before running CLI inspection commands

Example fix

// before
const code = await cli.run("get-shader-code", { uniqueId: "123" });
// after
await scene.whenReadyAsync();
scene.render();
const code = await cli.run("get-shader-code", { uniqueId: "123" });
Defensive patterns

Strategy: validation

Validate before calling

const material = scene.materials.find((m) => m.uniqueId === id);
const effect = material?.getEffect();
if (!effect || !effect.isReady()) {
    await scene.whenReadyAsync();
    scene.render(); // force one frame so the effect compiles
}

Type guard

function isEffectReady(material: BABYLON.Material | undefined): material is BABYLON.Material & { getEffect(): BABYLON.Effect } {
    const effect = material?.getEffect();
    return !!effect && effect.isReady();
}

Try / catch

try {
    const code = await cli.run("get-shader-code", { uniqueId });
} catch (err) {
    if (String(err).includes("effect is not ready")) {
        await scene.whenReadyAsync();
        return retryGetShaderCode(uniqueId);
    }
    throw err;
}

Prevention

When it happens

Trigger: Calling get-shader-code with a valid material uniqueId immediately after creating the material or assigning it to a mesh, before the first frame that uses the material has been rendered (shader still compiling, or shader compilation failed and never became ready).

Common situations: Querying shaders right after scene setup without rendering a frame; material created but never bound to an active mesh; shader compilation error keeping isReady() false forever; headless/CLI usage where no render loop runs to drive compilation.

Related errors

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