Web SDK - Why am I getting a black camera screen?

If you can't access the camera in your implementation, try rebooting your device and see if it works.

If the issue persists, it might be caused by one of the following reasons: 

  1. missing permission / request, e.g. when using WebSDK inside a WebView. Here you can find our official samples showing how to handle needed permission:

  2. other resource (app, tab) still using the camera or not yet fully releasing it.

  3. previous instance of the scanner not yet fully releasing it (this happens when scanner is not used as a singleton).

  4. user refusing the access.

  5. camera stream / access being explicitly stopped and not resumed.

The following article describes the steps to debug the possible root cause of your issue:


More details on the reasons it might fail:

  • No secure context is used (i.e. http: instead of https: when not on localhost or local IP).
  • Browsers can be set to either globally or per-website automatically deny camera access requests, without showing such permission requests to the user. In this case the browser settings need to be changed to allow for camera access (via permission requests) globally and/or clear the specific website's permissions data in order to allow camera access requests to be correctly executed again, asking for user permission.
  • Browsers can rarely get in a state where any kind of camera access will fail. In this case, a reboot of the device is needed and will solve the issue.
  • Browsers can be set to be denied from accessing cameras from the OS. In this case, a change of device settings and restart of the browser is needed to allow for camera access.
  • The website is set to not allow camera access via a Feature-Policy/Permission-Policy HTTP header containing a restrictive camera directive.
  • A cross-origin iframe is used with no allow attribute containing the camera feature.
  • Some cameras are listed by enumerateDevices but can then never be accessed by the browser via getUserMedia, this is for instance the case for infrared cameras present on some devices. Our library tries to automatically ignore such cameras and to recover from this situation by switching to another camera when this happen, but if no other camera is present or the user specifically asks to access the inaccessible camera, the error can happen.
  • The user might try to incorrectly try to access a camera via our library while said camera is already being accessed by another app/webpage, some other external logic, or immediately or shortly after its access was stopped. The camera needs to be inactive and there needs to be a delay of a second or so between the moment the camera access was stopped from the moment it is accessed again. Depending on the OS and browser it might be possible to have concurrent apps/webpages access the camera at the same time, however this shouldn't be relied on. This is handled automatically internally by our library, but there's no way for us to correctly detect and react to incorrect external camera access.
  • The user might try to incorrectly try to copy and store/cache camera device identifiers or objects by themselves in order to try to access them again after a page reload/navigation or camera access stop event. As said events can and will invalidate previous IDs, trying to access old cameras will fail.
  • The user might be using a custom webview/environment or code providing/overriding non-standard getUserMedia and/or enumerateDevice functions.


In case your issue persists, please contact us directly by submitting a support request.

Ideally, please also provide all the related information to speed up the investigation process on our end.

Was this article helpful?
2 out of 11 found this helpful
Have more questions? Submit a request