The ultimate guide to Lightning issues

Tutorials
1

The ultimate guide to Lightning issues

Have a Lightning related issue! We are here to help, let’s get into it.
In order to help you best it is important to establish what kind of issue you are dealing with.

Before we start make sure you understand the embedded development principles that enable you to be more successful in writing Lightning based apps for embedded devices.

Now we got that out of the way, let’s try to identify the issue you are having:

I tried something in Lightning, but I’m not getting the expected result

Please hop over to our community forum, search if someone already had a similar issue. If not feel free to create a new topic and wait for the community to come help you out.

Alternatively have a look at our reference applications and examples for inspiritation.

I have a memory leak in my App

Sorry to hear! Memory leaks can be daunting. Please read this before you start.
It is important you isolate the memory leak, is it JS Heap or Graphics memory related?

JS Heap related memory leak is typically code in your app or your dependencies. Please use the above guide to find/hunt down your memory leak and try to close it.
Graphics are hopefully easier to solve, follow the above guide for a strategy to pin-point the issue.

If you need an extra set of eyes on a section of code, create a snippet that is causing your app to leak and feel free to create a post on our community forum to share it for extra review.

Most of the time memory leaks are project specific and not Lightning core related. Lightning itself goes through extensive testing for memory leaks. Still convinced it is a Lightning originated memory leak and not your own code? Please read instructions below on how to file a Lightning bug

My app crashes!

Very likely a memory related issue, see the above “I have a memory leak in my App” section. Monitor the memory while you load up the application.
Additionally try to capture the console.log output of the browser and look for anything suspicious in the logs.

Couple of other things you may want to check:

  • Is it only your app or do all apps crash? If all apps crash you might have broader browser issues
  • Do other Lightning apps work well on your device? If all Lightning apps crash, the browser might have WebGL or rendering related issues. Graphics memory might be too low or the browser might not fully support WebGL
  • If it only your app that crashes? Going out of memory is very likely.

I’m getting WebGL errors!

WebGL errors are reported on the console.log of the Lightning application inside the browser, please investigate the WebGL error and consult your browser integration team for further assistance of the meaning of the error. It may be that certain shaders/extensions are not supported or there might be lower level OpenGL errors on the device.

Try loading a very simple Lightning (or any other WebGL app) and see if the errors persist. Certain WebGL extensions might not work properly, either way this is typically a platform issue as Lightning expects WebGL 1 to be fully supported.

My performance is bad

Dealing with performance is a whole different struggle, Lightning surely helps in getting you the best performance out there but incorrect usage may result into negatively impacted performance. Be sure to read theembedded development principles when looking at performance.

Please find our performance guide here.

Hopefully this will enable you to smoothen out your performance issues within your project.

I dont see anything on screen

Please check if your browser on your device supports WebGL. Try loading a standalone WebGL experiment and see if that works.
If you can’t get normal WebGL to work, Lightning won’t work either. Though you could try to see if falling back on Canvas2D helps (though the experience/performance will be diminished) please see the configuration section of Lightning and enable canvas2d : true in the stage configuration.

If this works but pure WebGL does not it is likely that your browser does not support WebGL.

If neither WebGL or Canvas2D work see if other HTML5 apps work by loading a standard web page in your browser, do those show up? If not, you might have generic browser issues. If a regular app works but neither Canvas2D or WebGL work both those two options might not be supported and Lightning can not be supported on your device.

I’m seeing artifacts!

Artifacts are never fun, though they happen! Couple of things we want to cross check though:

  • Does it only happen on a specific device? If so it might be device related
  • Can we reproduce it on our devices? E.g. on a dev machine, an RPI or common STB?
  • Is there a particular element/shader/animation that is causing the artifacts to appear?

If those can be answered please hop over to the how to file a Lightning bug chapter to further see how to deal with a Lightning bug.

My video playback doesn’t work

I’m sorry but video playback is outside of the scope of Lightning. Your browser has generic video playback support and you will need to work with the browser integration or app integration team to figure out which video playback method is best suitable for your project/device.

If you are running an RDK based embedded device, hop over to RDK for documentation/support on video playback on RDK based devices.

I found a bug in Lightning

That happens! And we’re very happy that you are here, bugs improve our project and we want to continue to make it better. Please scroll down to how to file a Lightning bug

I have suggestions to make Lightning better

Suggestions are always welcome! Please scroll down to how to file a Lightning bug and read the suggestions note.

I want to make a code contribution

Have a seat friend, don’t be shy. You’re among friends and please all contributions are welcome. Head over to our code contributions chapter for more information.

How to file a Lightning bug

Before we get to file a Lightning bug there are a couple of things we need to cross check.

First start by entering a search on your particular issue over at the forum to see if it has been addressed/discussed before.

Second search in the existing github issue list and see if the issue already has been reported.

But which github link do I use? Good question, it depends on where you suspect the issue might be. Follow the following guidelines:

Go to the issues section and search for an approximate description of the issue you are having. Be sure to check closed issues too to avoid reporting something that has already been solved but is still pending release or on a newer release than you are using.

If your issue is already reported, please add to the same thread and do not start a new one.

Your issue has not been reported before?

OK! Before we can post a new issue this is a check list of things that you’ll need:

  • Clear description of the problem “What is happening?”
  • Reproduction scenario “How is it happening?”
  • Code snippet of where it occurs “Where is it happening?”
  • Create a sample app that demonstrates the issue and provide a link if the snippet doesn’t cover it “Show us where it is happening”
  • Does it happen on Safari/Chrome? Or is it device related? “What device does it happen on?”
  • Having a screenshot or video sample that demonstrates the issue helps tremendously
  • Any relevant Lightning/WebGL/Browser related log lines when the issue happens

In order for us to take a look we need to be able to, quickly, reproduce the issue without debugging an entire project worth of code.
Couple of things to keep in mind:

  • Can we easily reproduce it?
  • Do we need specialized devices/access to see the issue?

Please capture all of the above in a github issue and create the ticket. Please be patient while one of the Lightning maintainers has a look.

Suggestions note
Have suggestions to make but don’t feel like contributing the changes yourself? That’s great! All ideas are welcome, please add the “What is happening” and “How your changes” would improve the situation. Be as verbose/elaborate as you can.

If you are unsure whether or not your suggestion make sense, consider creating a forum before raising a github issue and get feedback through there.

Code contributions

Feel free to fork the repository, put your changes in a branch and generate a pull request to the main repository with your code contributions. If you are new to Pull Requests please read this. You do not need to ask for our permission to create a PR (Pull Request), just fire whenever you are ready!

What determines if you are ready? Use this little handy-dandy check list:

  • The code must be complete, including any documentation/packager/etc changes if those are affected
  • Please provide a sample snippet if you are changing developer functionality in the PR
  • Please provide a test app to validate your new feature in your PR (a link)
  • Make sure your changes are tested and validated for memory leaks
  • Please ensure it doesn’t break other features of Lightning, use a reference app to validate if everything still works
  • Write why you’ve made those changes and how this improves the situation in the PR

Once the PR is made one of the Lightning team leads will have a look, your code will be reviewed and if we find something that we don’t agree with or like to see changes/clarification we’ll answer in the PR thread itself. Once everyone agrees the code will be merged in and made available in the next release!

3 Likes
2

Awesome guide! Thanks!

3

Can this post get pinned?

5

Sure thing! It’s pinned globally now.

1 Like
6

Thank you. I have started my journey in LJS3