Troubleshooting Guide

While developing with ScrollMagic something got stuck and you don't know what went wrong?
To help you get to the bottom of it, please follow this guide:

1. Is your console clean?

ScrollMagic spits out a lot of useful debugging information to the console of your browser. So make sure to check it first when inspecting the problem.
In Chrome the console is opened by clicking "View → Developer → JavaScript console".

Please note that most logging features are disabled for the minified version due to size considerations, so always make sure to use the unminified version during development!

If no errors appear, make use of ScrollMagic's debugging capabilities. Both the controller class as well as the scene class offer the loglevel option, and when set to 3 it will output even more useful information.

• Does the controller update, when you scroll?
• Is your scene object behaving correctly?
• Do the events trigger at the correct position?

Here's an example of all the things the console can tell you when used correctly.

2. Is there a problem with the animations?

2.1 Make sure they're happening at the correct scroll position.

Quite often the reason you don't see your animations playing is because they're happening outside of the viewport either before you scrolled past the element you're animating or immediately following.

An easy way to make sure is to add visual help by including the ScrollMagic indicators plugin.

Simply add the file reference into your html:

<script type="text/javascript" src="scrollmagic/uncompressed/plugins/debug.addIndicators.js"></script>

Now you can use scene.addIndicators() to add visual indicators showing you exactly where your scene will start and stop.

2.2 Make sure it's a ScrollMagic issue and not related to your animation framework.

Many animation-related issues are caused by an animation framework (GSAP/Velocity) or a misuse thereof. A very common mistake for example, is that the selector for TweenMax turns up empty.

For GSAP the recommended best practice is to create your tweens, but refrain from adding them to the ScrollMagic scene object using setTween. This ensures that ScrollMagic doesn't manipulate the animations in any way.
If you have a look at your site now, you can check if the animations plays out the way you wanted to. If they don't, the problem is obviously not rooted in ScrollMagic.

Check out the GreenSock Forums to get help using GSAP.
Get help for VelocityJS on their GitHub issues page.

Once you have your animation playing as intended, add it to the ScrollScene.

Hint: If your animation is further down in the DOM and you can't reach it before it plays, just add a delay to it. Just don't forget to remove it once everything animates like you want it to.

3. Isolate the issue

Some problems are caused by other elements, scripts or overlapping scenes on the page. Try to make a separate test-page containing only the respective scene. This will help you isolate the issue or lead you towards problems that come from other elements on the page.

4. Search for similar problems

Chances are someone already ran across something similar to what you're experiencing.
Check stackoverflow or use the GitHub search at the top of the page to see if there's already a solution waiting for you.

Happy Bughunting!