{"record":{"id":"631972c051f6c12c","repo":"BabylonJS/Babylon.js","slug":"advanceddynamictexture-name-the-texture-must","errorCode":null,"errorMessage":"AdvancedDynamicTexture \"${name}\": the texture must have been created with the useStandalone property set to true","messagePattern":"AdvancedDynamicTexture \"(.+?)\": the texture must have been created with the useStandalone property set to true","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/dev/gui/src/2D/FrameGraph/guiTask.ts","lineNumber":49,"sourceCode":"     */\r\n    public get gui() {\r\n        return this._adt;\r\n    }\r\n\r\n    protected _adt: AdvancedDynamicTexture;\r\n\r\n    /**\r\n     * Constructs a new GUI task.\r\n     * @param name Name of the task\r\n     * @param frameGraph Frame graph the task belongs to\r\n     * @param adt The GUI texture. If not provided, a new fullscreen GUI will be created.\r\n     */\r\n    constructor(name: string, frameGraph: FrameGraph, adt?: AdvancedDynamicTexture) {\r\n        super(name, frameGraph);\r\n\r\n        if (adt) {\r\n            if (!adt.useStandalone) {\r\n                throw new Error(`AdvancedDynamicTexture \"${name}\": the texture must have been created with the useStandalone property set to true`);\r\n            }\r\n        } else {\r\n            adt = AdvancedDynamicTexture.CreateFullscreenUI(name, undefined, { useStandalone: true, scene: frameGraph.scene });\r\n        }\r\n        this._adt = adt;\r\n\r\n        this.outputTexture = this._frameGraph.textureManager.createDanglingHandle();\r\n    }\r\n\r\n    public override isReady() {\r\n        return this._adt.guiIsReady() && this._adt._layerToDispose!.isReady();\r\n    }\r\n\r\n    public override getClassName(): string {\r\n        return \"FrameGraphGUITask\";\r\n    }\r\n\r\n    public record(): void {\r","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/gui/src/2D/FrameGraph/guiTask.ts#L31-L67","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Recreate the texture with useStandalone: true: AdvancedDynamicTexture.CreateFullscreenUI(name, undefined, { useStandalone: true, scene: frameGraph.scene })","Or omit the adt argument and let the constructor create a correct standalone texture for you","If you must reuse an existing ADT, rebuild it as standalone rather than passing the non-standalone instance"],"exampleFix":"// before\nconst adt = AdvancedDynamicTexture.CreateFullscreenUI('ui', true, scene);\nconst task = new GuiTask('gui', frameGraph, adt); // throws\n// after\nconst adt = AdvancedDynamicTexture.CreateFullscreenUI('ui', undefined, { useStandalone: true, scene: frameGraph.scene });\nconst task = new GuiTask('gui', frameGraph, adt);","handlingStrategy":"validation","validationCode":"function assertStandaloneAdt(adt: BABYLON.GUI.AdvancedDynamicTexture): void {\n  if (!adt.useStandalone) {\n    throw new Error('ADT must be created with useStandalone: true for frame-graph GUI tasks');\n  }\n}\n// call before new GuiTask(name, frameGraph, adt)","typeGuard":"function isStandaloneAdt(adt: BABYLON.GUI.AdvancedDynamicTexture): boolean {\n  return adt.useStandalone === true;\n}","tryCatchPattern":"try {\n  const task = new GuiTask(name, frameGraph, adt);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('useStandalone')) {\n    adt = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI(name, undefined, { useStandalone: true, scene: frameGraph.scene });\n    task = new GuiTask(name, frameGraph, adt);\n  } else { throw e; }\n}","preventionTips":["When targeting the frame-graph API, always pass { useStandalone: true } to CreateFullscreenUI","Or simply omit the adt parameter and let GuiTask construct a standalone texture","Never reuse scene-managed fullscreen ADTs in frame-graph GUI tasks","Add a useStandalone assertion in helper wrappers around GuiTask construction"],"tags":["babylonjs","gui","frame-graph","advanced-dynamic-texture","configuration"],"backgroundTag":"adt-must-be-standalone","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-31T09:17:48.483Z"}