{"record":{"id":"8d4b932a0858cc6d","repo":"BabylonJS/Babylon.js","slug":"unable-to-create-occlusion-query","errorCode":null,"errorMessage":"Unable to create Occlusion Query","messagePattern":"Unable to create Occlusion Query","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/dev/core/src/Engines/Extensions/engine.query.pure.ts","lineNumber":23,"sourceCode":"import { type OcclusionQuery } from \"../AbstractEngine/abstractEngine.query.pure\";\r\nimport { ThinEngine } from \"../../Engines/thinEngine.pure\";\r\nimport { _TimeToken } from \"../../Instrumentation/timeToken\";\r\n\r\nlet _Registered = false;\r\n/**\r\n * Register side effects for enginesExtensionsEngineQuery.\r\n * Safe to call multiple times; only the first call has an effect.\r\n */\r\nexport function RegisterEnginesExtensionsEngineQuery(): void {\r\n    if (_Registered) {\r\n        return;\r\n    }\r\n    _Registered = true;\r\n\r\n    ThinEngine.prototype.createQuery = function (): OcclusionQuery {\r\n        const query = this._gl.createQuery();\r\n        if (!query) {\r\n            throw new Error(\"Unable to create Occlusion Query\");\r\n        }\r\n        return query;\r\n    };\r\n\r\n    ThinEngine.prototype.deleteQuery = function (query: OcclusionQuery): ThinEngine {\r\n        this._gl.deleteQuery(query);\r\n\r\n        return this;\r\n    };\r\n\r\n    ThinEngine.prototype.isQueryResultAvailable = function (query: OcclusionQuery): boolean {\r\n        return this._gl.getQueryParameter(query, this._gl.QUERY_RESULT_AVAILABLE) as boolean;\r\n    };\r\n\r\n    ThinEngine.prototype.getQueryResult = function (query: OcclusionQuery): number {\r\n        return this._gl.getQueryParameter(query, this._gl.QUERY_RESULT) as number;\r\n    };\r\n\r","sourceCodeStart":5,"sourceCodeEnd":41,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/core/src/Engines/Extensions/engine.query.pure.ts#L5-L41","documentation":"ThinEngine.createQuery wraps gl.createQuery() to allocate a WebGL occlusion query object. WebGL guarantees non-null in spec-compliant implementations, but if the underlying GL call returns null (context lost or driver failure) Babylon throws this error instead of returning an invalid query handle. Any use of scene.setRenderingAutoClearDepthStencil with occlusion or the OcclusionQuery API can hit it.","triggerScenarios":"Calling ThinEngine.createQuery() (directly or via mesh occlusion queries: mesh.alwaysSelectAsActiveMesh=false with occlusion enabled) when the WebGL context is lost or gl.createQuery() fails.","commonSituations":"Tab/background context loss while using occlusion queries; old drivers with faulty query object allocation; running occlusion queries after GPU reset; heavy use of many query objects.","solutions":["Listen for 'webglcontextlost' and re-create the engine/restore context","Wrap query creation in try-catch and disable occlusion queries on failure","Reduce number of meshes using occlusion queries","Update GPU/browser to fix driver-level query creation bugs","Re-run the operation after context restore (webglcontextrestored)"],"exampleFix":"// before\nconst query = engine.createQuery();\n// after\nlet query = null;\ntry {\n  query = engine.createQuery();\n} catch (e) {\n  mesh.occlusionQueryEnabled = false; // degrade gracefully\n}","handlingStrategy":"try-catch","validationCode":"function canCreateQuery(engine) {\n  return !engine.isDisposed && !!(engine as any)._gl && typeof (engine as any)._gl.createQuery === 'function';\n}","typeGuard":"function hasLiveContext(engine): boolean {\n  return !engine.isDisposed && !!(engine as any)._gl;\n}","tryCatchPattern":"let query: BABYLON.OcclusionQuery | null = null;\ntry {\n  query = engine.createQuery();\n} catch (e) {\n  if (String(e?.message).includes('Occlusion Query')) {\n    mesh.occlusionQueryEnabled = false; // disable occlusion queries\n  } else { throw e; }\n}","preventionTips":["Handle webglcontextlost/restored and rebuild queries after restore","Limit how many meshes use occlusion queries","Disable occlusion queries as a graceful degradation path","Avoid creating queries after engine.dispose()","Test on browsers/drivers used by your audience"],"tags":["webgl","occlusion-query","context-loss"],"backgroundTag":"webgl-object-creation-failed","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-31T09:17:48.483Z"}