{"record":{"id":"f375e44225f2b19a","repo":"BabylonJS/Babylon.js","slug":"the-provided-canvas-is-null-or-undefined","errorCode":null,"errorMessage":"The provided canvas is null or undefined.","messagePattern":"The provided canvas is null or undefined\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/dev/core/src/Engines/thinEngine.pure.ts","lineNumber":383,"sourceCode":"                    this._gl = <any>(canvas.getContext(\"webgl2\", options) || canvas.getContext(\"experimental-webgl2\", options));\r\n                    if (this._gl) {\r\n                        this._webGLVersion = 2.0;\r\n                        this._shaderPlatformName = \"WEBGL2\";\r\n\r\n                        // Prevent weird browsers to lie (yeah that happens!)\r\n                        if (!this._gl.deleteQuery) {\r\n                            this._webGLVersion = 1.0;\r\n                            this._shaderPlatformName = \"WEBGL1\";\r\n                        }\r\n                    }\r\n                } catch (e) {\r\n                    // Do nothing\r\n                }\r\n            }\r\n\r\n            if (!this._gl) {\r\n                if (!canvas) {\r\n                    throw new Error(\"The provided canvas is null or undefined.\");\r\n                }\r\n                try {\r\n                    this._gl = <WebGL2RenderingContext>(canvas.getContext(\"webgl\", options) || canvas.getContext(\"experimental-webgl\", options));\r\n                } catch (e) {\r\n                    throw new Error(\"WebGL not supported\", { cause: e });\r\n                }\r\n            }\r\n\r\n            if (!this._gl) {\r\n                throw new Error(\"WebGL not supported\");\r\n            }\r\n        } else {\r\n            this._gl = <WebGL2RenderingContext>canvasOrContext;\r\n            canvas = this._gl.canvas as HTMLCanvasElement;\r\n\r\n            if ((this._gl as any).renderbufferStorageMultisample) {\r\n                this._webGLVersion = 2.0;\r\n                this._shaderPlatformName = \"WEBGL2\";\r","sourceCodeStart":365,"sourceCodeEnd":401,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/core/src/Engines/thinEngine.pure.ts#L365-L401","documentation":"ThinEngine's constructor throws this when the engine could not obtain a WebGL context AND the canvas argument passed in is null or undefined. Before attempting canvas.getContext('webgl'), the code guards that a canvas exists; if none was given the engine cannot proceed at all.","triggerScenarios":"new Engine(null), new Engine(undefined), passing a variable that is not yet assigned, or passing the result of a failed lookup (e.g. document.getElementById('missing')) which returns null.","commonSituations":"DOM element queried before it exists (script running before DOM ready); typo in canvas element id; passing null deliberately in tests; refactoring code so the canvas variable is uninitialized at engine construction.","solutions":["Pass a real canvas element (or an existing WebGL context) to the Engine constructor","Ensure the DOM is loaded before querying the canvas (script at end of body or DOMContentLoaded)","Check that document.getElementById/getElementByClassName returns the intended element","Null-check the canvas before constructing the engine"],"exampleFix":"// before\nconst canvas = document.getElementById('renderCanvas'); // null if id typo / not in DOM yet\nconst engine = new Engine(canvas, true);\n// after\nconst canvas = document.getElementById('renderCanvas') as HTMLCanvasElement;\nif (!canvas) throw new Error('renderCanvas element missing');\nconst engine = new Engine(canvas, true);","handlingStrategy":"type-guard","validationCode":"function requireCanvas(el: HTMLElement | null | undefined): HTMLCanvasElement {\n  if (!el || !(el instanceof HTMLCanvasElement)) throw new Error('Valid canvas element required');\n  return el;\n}","typeGuard":"function isCanvas(v: unknown): v is HTMLCanvasElement {\n  return typeof HTMLCanvasElement !== 'undefined' && v instanceof HTMLCanvasElement;\n}","tryCatchPattern":"try {\n  const engine = new Engine(canvas as HTMLCanvasElement, true);\n} catch (e) {\n  if ((e as Error).message.includes('canvas is null')) {\n    console.error('Canvas element missing — check DOM id and load order');\n  }\n}","preventionTips":["Initialize the engine after DOMContentLoaded or place scripts at end of body","Log document.getElementById(...) results during setup debugging","Type the canvas parameter as HTMLCanvasElement so null is caught at compile time","Centralize engine creation in one factory function with canvas validation"],"tags":["webgl","canvas","argument-validation"],"backgroundTag":"null-or-undefined-argument","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-30T18:17:15.746Z"}