WebGL troubleshooting


I got “The browser supports WebGL, but initialization failed” error on an Android tablet.

No spinning cube on https://get.webgl.org/.

How to troubleshoot this?

More importantly, our users (testers) get the same error and we need to help them.

Can we do any better than asking to upgrade their video driver and browser and then give up?

Ideally, I’m looking for a resource which could help an average user to make Cesium run in her environment.

Please, advise.

Thank you.

No spinning cube means it’s a WebGL issue and not a Cesium issue, so there’s nothing you can do without fixing the real problem (WebGL being unavailable).

The standard procedure on the desktop:

  1. Update video drivers to latest version

  2. Update to latest browser version

  3. Try all 3 browsers to see if any of them work. (Chrome/Firefox/IE11 or Safari)

  4. If on Windows or Safari, make sure you have all OS updates applied, as they both include browser updates as well.

  5. If the first 3 fail, the last shot is to see your video card is blacklisted by the browser (for known bugginess) and override the blacklist if desired. This is browser specific.

In this day and age getting to step 5 should be an incredibly rare occurrence. Most are fixed at step 1 or 2 unless the user has really old hardware.

For mobile/tablets, it’s tricky because you have a lot less control.

All iOS 8 devices support WebGL, so you will never get a failure there (but Safari itself is pretty buggy).

Android devices require either Chrome or Firefox but if it doesn’t work on either of them you don’t have many options. Make sure you have the latest version of Android available for the device. You can also override the blacklist if WebGL is blocked, but doing that is browser specific.

Is there an easy way to check if Cesium has found an acceptable version of WebGL?

We have an application that can fall back to a non cesium 2D mode if Cesium cannot be supported so want to do that check when the application is launched.

Thanks, Ian

On Behalf Of Matthew Amato

Hello Ian, we have something similar as well, and we tried many different checks for WebGL compatibility, but found that we could foil just about every one of them with all of the weird hardware we’re dealing with. We ended up just using a hammer and putting a try/catch around the Cesium.Viewer instantiation, and then redirecting to our fallback inside the catch. Not the most efficient way, but it was the only way we’ve found so far to handle every single bizarre case that we find in our environment. Something like this:

viewer = new Cesium.Viewer(‘cesiumContainer’, {
infoBox: false

Di’s approach is the most foolproof. The main problem is that some older browsers (like Safari before iOS8) claim to support WebGL but then throw an error if you try and actually use it. Basically the browser lies and actually running Cesium is the only way to determine if the browser can run Cesium.

How can I suppress default message box upon Cesium widget creation failure?

Thank you.

Viewer and CesiumWidget have a constructor option showRenderLoopErrors which can be set to false.


Thanks, but Cesium Widget creation is not a render loop, so this flag doesn’t prevent the message.

I just opened https://github.com/AnalyticalGraphicsInc/cesium/pull/2710 to make the construction error obey the showRenderLoopErrors flag, while technically not a render loop error, it is similar enough that I think this is the correct fix.

Can anything be done if the cube IS spinning but Cesium still fails to initialize WebGL?

Thank you.

Assuming that you follow steps 1-4, that sounds like an extraordinary situation. The only way I could see that happening is if you de-blacklisted the driver in step 5, in which case you are out of luck (cards are blacklisted for a reason). If you do have a user seeing such a problem, let us know. The info that we would need to even begin to speculate on the problem would be is:

  1. Exact OS version being used.

  2. Exact Browser version being used.

  3. webglreport.com output for WebGL 1 tab from browser being used.

  4. Exact video card model and driver version being used.

Most of the time this problem happens, it will not be Cesium but the browser/os/video card causing the issue, at which point there’s not much we can do.