BabylonJS/Babylon.js · error

AdvancedDynamicTexture "${name}": the texture must have been

Error message

AdvancedDynamicTexture "${name}": the texture must have been created with the useStandalone property set to true

What it means

The FrameGraph GUI task (GuiTexture/GUI rendering task) requires the supplied AdvancedDynamicTexture to be standalone — i.e. it owns its rendering pipeline and is not tied to a fullscreen pass managed elsewhere. If the passed adt was created without useStandalone: true, the constructor throws because the frame-graph task cannot take over a non-standalone texture.

Source

Thrown at packages/dev/gui/src/2D/FrameGraph/guiTask.ts:49

     */
    public get gui() {
        return this._adt;
    }

    protected _adt: AdvancedDynamicTexture;

    /**
     * Constructs a new GUI task.
     * @param name Name of the task
     * @param frameGraph Frame graph the task belongs to
     * @param adt The GUI texture. If not provided, a new fullscreen GUI will be created.
     */
    constructor(name: string, frameGraph: FrameGraph, adt?: AdvancedDynamicTexture) {
        super(name, frameGraph);

        if (adt) {
            if (!adt.useStandalone) {
                throw new Error(`AdvancedDynamicTexture "${name}": the texture must have been created with the useStandalone property set to true`);
            }
        } else {
            adt = AdvancedDynamicTexture.CreateFullscreenUI(name, undefined, { useStandalone: true, scene: frameGraph.scene });
        }
        this._adt = adt;

        this.outputTexture = this._frameGraph.textureManager.createDanglingHandle();
    }

    public override isReady() {
        return this._adt.guiIsReady() && this._adt._layerToDispose!.isReady();
    }

    public override getClassName(): string {
        return "FrameGraphGUITask";
    }

    public record(): void {

View on GitHub (pinned to 0592b347b8)

Solutions

1. Recreate the texture with useStandalone: true: AdvancedDynamicTexture.CreateFullscreenUI(name, undefined, { useStandalone: true, scene: frameGraph.scene })
2. Or omit the adt argument and let the constructor create a correct standalone texture for you
3. If you must reuse an existing ADT, rebuild it as standalone rather than passing the non-standalone instance

Example fix

// before
const adt = AdvancedDynamicTexture.CreateFullscreenUI('ui', true, scene);
const task = new GuiTask('gui', frameGraph, adt); // throws
// after
const adt = AdvancedDynamicTexture.CreateFullscreenUI('ui', undefined, { useStandalone: true, scene: frameGraph.scene });
const task = new GuiTask('gui', frameGraph, adt);

function assertStandaloneAdt(adt: BABYLON.GUI.AdvancedDynamicTexture): void {
  if (!adt.useStandalone) {
    throw new Error('ADT must be created with useStandalone: true for frame-graph GUI tasks');
  }
}
// call before new GuiTask(name, frameGraph, adt)

function isStandaloneAdt(adt: BABYLON.GUI.AdvancedDynamicTexture): boolean {
  return adt.useStandalone === true;
}

try {
  const task = new GuiTask(name, frameGraph, adt);
} catch (e) {
  if (e instanceof Error && e.message.includes('useStandalone')) {
    adt = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI(name, undefined, { useStandalone: true, scene: frameGraph.scene });
    task = new GuiTask(name, frameGraph, adt);
  } else { throw e; }
}

When it happens

Trigger: Constructing new GuiTask(name, frameGraph, adt) where adt was created via AdvancedDynamicTexture.CreateFullscreenUI(...) (default non-standalone) or new AdvancedDynamicTexture(rt, false); only adt.useStandalone === true is accepted.

Common situations: Migrating legacy GUI code to the frame-graph API and reusing an existing fullscreen ADT; copying CreateFullscreenUI calls that default useStandalone to false; confusion between scene-based ADT and standalone/frame-graph ADT in Babylon.js GUI versions.

Related errors

• FrameGraphDepthOfFieldBlurTask "${this.name}": sourceTexture
• FrameGraphBloomMergeTask "${this.name}": sourceTexture, circ
• FrameGraphDepthOfFieldTask: sourceTexture, depthTexture and
• FrameGraphMotionBlurTask "${this.name}": sourceTexture is re
• FrameGraphMotionBlurTask "${this.name}": velocityTexture is

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