{"record":{"id":"1c467035492c7438","repo":"pixijs/pixijs","slug":"no-available-renderer-for-the-current-environment","errorCode":null,"errorMessage":"No available renderer for the current environment","messagePattern":"No available renderer for the current environment","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/rendering/renderers/autoDetectRenderer.ts","lineNumber":169,"sourceCode":"        else if (rendererType === 'canvas')\n        {\n            const { CanvasRenderer } = await import('./canvas/CanvasRenderer');\n\n            RendererClass = CanvasRenderer;\n\n            finalOptions = { ...options, ...options.canvasOptions };\n\n            break;\n        }\n    }\n\n    delete finalOptions.webgpu;\n    delete finalOptions.webgl;\n    delete finalOptions.canvasOptions;\n\n    if (!RendererClass)\n    {\n        throw new Error('No available renderer for the current environment');\n    }\n\n    const renderer = new RendererClass();\n\n    await renderer.init(finalOptions);\n\n    return renderer;\n}\n","sourceCodeStart":151,"sourceCodeEnd":178,"githubUrl":"https://github.com/pixijs/pixijs/blob/4b141e3ced7255b39c2114b6bca03421a37b2363/src/rendering/renderers/autoDetectRenderer.ts#L151-L178","documentation":"autoDetectRenderer iterates candidate renderer classes gated by the webgpu/webgl/canvasOptions flags; if none of the candidates is available (all skipped due to environment unsupported or options disabled), RendererClass stays undefined and the function throws. It is the top-level fallback when no backend can be selected.","triggerScenarios":"Setting both options.webgpu=false and options.webgl=false in an environment with no canvas fallback; running in a non-browser JS runtime (Node without canvas polyfill); a browser with no WebGPU and WebGL disabled by the user.","commonSituations":"Server-side rendering or unit tests without a DOM/canvas shim; explicitly disabling all GPU backends for testing; very old browsers with no WebGL; misconfigured bundler that tree-shakes the renderer classes.","solutions":["Ensure at least one backend is permitted (leave webgl/webgpu defaults, or enable options.canvas for the software renderer).","In Node/test environments, provide a canvas polyfill (e.g. node-canvas, jsdom + webgl mock).","Verify the Pixi build includes the renderer classes you expect (check bundle/imports).","Detect environment capabilities before calling autoDetectRenderer and surface a clear message."],"exampleFix":"// before\nconst renderer = await autoDetectRenderer({ webgpu: false, webgl: false });\n\n// after\nconst renderer = await autoDetectRenderer({ webgpu: false }); // webgl/canvas still allowed","handlingStrategy":"validation","validationCode":"const caps = {\n  webgpu: typeof navigator !== 'undefined' && !!navigator.gpu,\n  webgl: typeof document !== 'undefined' && !!document.createElement('canvas').getContext('webgl'),\n};\nif (!caps.webgpu && !caps.webgl) {\n  throw new Error('No GPU backend available; enable canvas renderer fallback');\n}","typeGuard":"function hasAnyBackend(): boolean {\n  return (typeof navigator !== 'undefined' && !!navigator.gpu)\n    || (typeof document !== 'undefined'\n      && !!document.createElement('canvas').getContext('webgl'));\n}","tryCatchPattern":"try {\n  renderer = await autoDetectRenderer(options);\n} catch {\n  renderer = await autoDetectRenderer({ ...options, webgpu: false, webgl: false, canvas: {} });\n}","preventionTips":["Do not disable every backend unless a software canvas fallback remains enabled.","Provide a canvas polyfill in Node/test environments.","Verify the bundle includes the renderer classes you need."],"tags":["renderer","environment","initialization","fallback","browser-support"],"backgroundTag":null,"analyzedSha":"4b141e3ced7255b39c2114b6bca03421a37b2363","analyzedAt":"2026-08-12T17:27:29.507Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}