{"record":{"id":"6058b28ed517efd6","repo":"phaserjs/phaser","slug":"matter-runner-missing-required-global-window-requ","errorCode":null,"errorMessage":"Matter.Runner: missing required global window.requestAnimationFrame.","messagePattern":"Matter\\.Runner: missing required global window\\.requestAnimationFrame\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/physics/matter-js/lib/core/Runner.js","lineNumber":200,"sourceCode":"     * If you wish to only temporarily pause the engine, see `engine.enabled` instead.\n     * @method stop\n     * @param {runner} runner\n     */\n    Runner.stop = function(runner) {\n        Runner._cancelNextFrame(runner);\n    };\n\n    /**\n     * Alias for `Runner.run`.\n     * @method start\n     * @param {runner} runner\n     * @param {engine} engine\n     */\n    Runner._onNextFrame = function(runner, callback) {\n        if (typeof window !== 'undefined' && window.requestAnimationFrame) {\n            runner.frameRequestId = window.requestAnimationFrame(callback);\n        } else {\n            throw new Error('Matter.Runner: missing required global window.requestAnimationFrame.');\n        }\n        return runner.frameRequestId;\n    };\n    Runner._cancelNextFrame = function(runner) {\n        if (typeof window !== 'undefined' && window.cancelAnimationFrame) {\n            window.cancelAnimationFrame(runner.frameRequestId);\n        } else {\n            throw new Error('Matter.Runner: missing required global window.cancelAnimationFrame.');\n        }\n    };\n\n    var _mean = function(values) {\n        var result = 0,\n            valuesLength = values.length;\n        for (var i = 0; i < valuesLength; i += 1) {\n            result += values[i];\n        }\n        return (result / valuesLength) || 0;","sourceCodeStart":182,"sourceCodeEnd":218,"githubUrl":"https://github.com/phaserjs/phaser/blob/41be1e462bc600064e498cba370bfa8c5c055a22/src/physics/matter-js/lib/core/Runner.js#L182-L218","documentation":"Runner.js:200 throws from `_onNextFrame` when `typeof window === 'undefined'` or `window.requestAnimationFrame` is missing. Matter's Runner schedules each physics tick via rAF; without it the loop cannot advance. This is Matter.js's hard dependency on a browser-like global.","triggerScenarios":"Running `Matter.Runner.run(runner, engine)` (or the Phaser Matter Physics system that uses it) in Node.js, a Web Worker without rAF polyfill, jsdom, or an SSR context where `window.requestAnimationFrame` is undefined.","commonSituations":"Server-side simulation/SSR that imports Phaser's Matter physics; unit tests in Node; rendering on the server with intent to step physics manually; bundlers that tree-shake the DOM globals.","solutions":["Run physics only in a browser context; for Node use a manual `Runner.tick(engine, delta)` loop or `Engine.update(engine, delta)` instead of `Runner.run`.","Polyfill `globalThis.requestAnimationFrame` (e.g. via a timer-based shim) before starting the Runner.","Use Phaser's HEADLESS mode for server stepping and avoid the Matter Runner's rAF scheduling."],"exampleFix":"// before\nMatter.Runner.create(engine) // then Runner.run under Node -> throws\n// after (Node)\nsetInterval(() => Matter.Engine.update(engine, 1000 / 60), 1000 / 60)","handlingStrategy":"validation","validationCode":"const hasRAF = typeof window !== 'undefined' && typeof window.requestAnimationFrame === 'function'\nif (!hasRAF) {\n  // Node/SSR: step manually instead of Runner.run\n  setInterval(() => Matter.Engine.update(engine, 1000 / 60), 1000 / 60)\n} else {\n  Matter.Runner.run(runner, engine)\n}","typeGuard":"const supportsRAF = () => typeof window !== 'undefined' && typeof window.requestAnimationFrame === 'function'","tryCatchPattern":null,"preventionTips":["Don't use Matter.Runner.run under Node; drive Engine.update manually.","Polyfill requestAnimationFrame if you must run the Runner in a worker/SSR.","Isolate physics stepping code from browser-only globals."],"tags":["physics","matter-js","environment","requestanimationframe"],"backgroundTag":null,"analyzedSha":"41be1e462bc600064e498cba370bfa8c5c055a22","analyzedAt":"2026-08-13T04:23:39.729Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}