{"record":{"id":"6edc7aedef25d52d","repo":"mrdoob/three.js","slug":"three-renderer-inittexture-called-before-the-b","errorCode":null,"errorMessage":"THREE.Renderer: .initTexture() called before the backend is initialized. Use \"await renderer.init();\" before using this method.","messagePattern":"THREE\\.Renderer: \\.initTexture\\(\\) called before the backend is initialized\\. Use \"await renderer\\.init\\(\\);\" before using this method\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/renderers/common/Renderer.js","lineNumber":3091,"sourceCode":"\t\tawait this.init();\n\n\t\tthis.initTexture( texture );\n\n\t}\n\n\t/**\n\t * Initializes the given texture. Useful for preloading a texture rather than waiting until first render\n\t * (which can cause noticeable lags due to decode and GPU upload overhead).\n\t *\n\t * This method can only be used if the renderer has been initialized.\n\t *\n\t * @param {Texture} texture - The texture.\n\t */\n\tinitTexture( texture ) {\n\n\t\tif ( this._initialized === false ) {\n\n\t\t\tthrow new Error( 'THREE.Renderer: .initTexture() called before the backend is initialized. Use \"await renderer.init();\" before using this method.' );\n\n\t\t}\n\n\t\tthis._textures.updateTexture( texture );\n\n\t}\n\n\t/**\n\t * Initializes the given render target.\n\t *\n\t * @param {RenderTarget} renderTarget - The render target to intialize.\n\t */\n\tinitRenderTarget( renderTarget ) {\n\n\t\tif ( this._initialized === false ) {\n\n\t\t\tthrow new Error( 'THREE.Renderer: .initRenderTarget() called before the backend is initialized. Use \"await renderer.init();\" before using this method.' );\n","sourceCodeStart":3073,"sourceCodeEnd":3109,"githubUrl":"https://github.com/mrdoob/three.js/blob/da05705fa31f02710c19772a2aa70c7454807f0c/src/renderers/common/Renderer.js#L3073-L3109","documentation":"Thrown by Renderer.initTexture() when the backend is not yet initialized. Texture preloading needs the GPU upload machinery (the _textures backend system) which is only available after renderer.init() resolves. The async init must complete before any manual texture upload.","triggerScenarios":"Calling renderer.initTexture(texture) right after `new WebGPURenderer()` (or any common Renderer subclass) without awaiting init, typically to preload a texture before the first render to avoid a startup hitch.","commonSituations":"App startup routines that preload env maps, fonts, or sprite atlases synchronously. Migrating from `initTextureAsync` (deprecated) without adding the explicit `await renderer.init()`. SSR/server code paths where init was never triggered.","solutions":["Call `await renderer.init();` before `renderer.initTexture(texture);`.","Switch to the deprecated `await renderer.initTextureAsync(texture)` which inits internally (emits deprecation warning).","Defer preloading until after the first render frame, which implicitly initializes the backend.","Group all preload calls behind an `async function prepareAssets()` that awaits init first."],"exampleFix":"// before\nconst renderer = new WebGPURenderer();\nrenderer.initTexture(envMap); // throws\n\n// after\nconst renderer = new WebGPURenderer();\nawait renderer.init();\nrenderer.initTexture(envMap);","handlingStrategy":"validation","validationCode":"async function preloadTexture(renderer, texture) {\n  if (!renderer.hasInitialized()) await renderer.init();\n  renderer.initTexture(texture);\n}","typeGuard":"function rendererReady(renderer) {\n  return typeof renderer.hasInitialized === 'function' && renderer.hasInitialized();\n}","tryCatchPattern":"try {\n  renderer.initTexture(texture);\n} catch (e) {\n  if (/initTexture\\(\\) called before/.test(e.message)) { await renderer.init(); renderer.initTexture(texture); }\n  else throw e;\n}","preventionTips":["Wrap all asset-preload routines in an async function whose first line is `await renderer.init();`.","Avoid calling initTexture from synchronous constructors or module top-level code.","Track readiness with renderer.hasInitialized() in your asset manager."],"tags":["webgpu","lifecycle","async-init","texture","renderer"],"backgroundTag":null,"analyzedSha":"da05705fa31f02710c19772a2aa70c7454807f0c","analyzedAt":"2026-08-12T22:51:37.160Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}