pixijs/pixijs · critical · Error

No available renderer for the current environment

Error message

No available renderer for the current environment

What it means

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.

Source

Thrown at src/rendering/renderers/autoDetectRenderer.ts:169

        else if (rendererType === 'canvas')
        {
            const { CanvasRenderer } = await import('./canvas/CanvasRenderer');

            RendererClass = CanvasRenderer;

            finalOptions = { ...options, ...options.canvasOptions };

            break;
        }
    }

    delete finalOptions.webgpu;
    delete finalOptions.webgl;
    delete finalOptions.canvasOptions;

    if (!RendererClass)
    {
        throw new Error('No available renderer for the current environment');
    }

    const renderer = new RendererClass();

    await renderer.init(finalOptions);

    return renderer;
}

View on GitHub (pinned to 4b141e3ced)

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.

Example fix

// before
const renderer = await autoDetectRenderer({ webgpu: false, webgl: false });

// after
const renderer = await autoDetectRenderer({ webgpu: false }); // webgl/canvas still allowed

Defensive patterns

Strategy: validation

Validate before calling

const caps = {
  webgpu: typeof navigator !== 'undefined' && !!navigator.gpu,
  webgl: typeof document !== 'undefined' && !!document.createElement('canvas').getContext('webgl'),
};
if (!caps.webgpu && !caps.webgl) {
  throw new Error('No GPU backend available; enable canvas renderer fallback');
}

Type guard

function hasAnyBackend(): boolean {
  return (typeof navigator !== 'undefined' && !!navigator.gpu)
    || (typeof document !== 'undefined'
      && !!document.createElement('canvas').getContext('webgl'));
}

Try / catch

try {
  renderer = await autoDetectRenderer(options);
} catch {
  renderer = await autoDetectRenderer({ ...options, webgpu: false, webgl: false, canvas: {} });
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of pixijs/pixijs@4b141e3ced (2026-08-12). Data as JSON: /api/errors/1c467035492c7438. Report an issue: GitHub.