Why does my debugger stop visually at the wrong line?

I am using

METEOR@1.4.4.2
WebStorm@2017.1.1 
Chrome@58.0.3029.110 (64-bit)
macOS Sierra 10.12.5
ecmascript@0.7.3
ecmascript-runtime@0.3.15

Recently, the debugger started to stop at wrong lines but only visually, mostly it is like 8-14 lines behind the actual breakpoint.

e.g.

*the orange bar indicates the breakpoint in google chrome

console output:

Also, as you can see, some lines are darkened, which means that I can not set a breakpoint there from the browser.

The behavior is the same within the WebStorm internal debugger. So I think it is not Chrome's fault. It looks like the source mapping is broken. I do not know if it is WebStorm, or Meteor that is the cause. Under this conditions it is very hard to debug...

Solution

It is difficult to say for sure, but it seems that the issue that you are experiencing is related to a bug that causes Meteor to generate incorrect source maps.

source maps

This is not your browser's "fault". It simply displays the code and the position that is delivered to it by the source maps in your project.

The app.js file and the source map (app.js.map) are generated by the Meteor build process and are served from the .meteor/local/build/programs/web.browser/app directory.

The .map file is responsible of telling the browser how to display the original source, and which segments in the generated app.js file are mapped to which segments in the original source code.

A great explanation about the technical aspects of source maps can be found here.

You can visualize your source maps online and see what maps where using this tool (choose custom... and drag/drop both .js and .map files.

the suspected bug

As a part of the build process, Meteor uses the babel-compiler Meteor package. At some point, a bug caused invalid maps to be produced after babel transformations.

The bug is currently tracked on GitHub and the Meteor folks seem to be closing in on the cause.

what can you do?

At the moment, there is no quick and easy fix.

You can either:

Watch the bug thread and wait for it to be resolved and debug without source maps for now (probably best, if the bug will be fixed soon).
Hack away with local clones of the relevant Meteor packages (could work, I haven't dug into the dependency issues and don't really recommend it, but here's a way of doing it).
Run Meteor from a git checkout in a known good state until a fix is released.

The last option is what @hwilson did in order to begin pinpointing the bug via a git bisect.

You can refer to the Meteor developer document for detailed information regarding the method of running the meteor tool from checkout, but the gist of the things is as follows:

First, make sure that your code, including the .meteor/versions and .meteor/packages are checked out into source control, as you will likely need to mess them up temporarily and will want to restore them once the bug is fixed.

git clone --recursive https://github.com/meteor/meteor.git to a directory of your choosing (e.g, /home/yourname/src/remote.
cd meteor.
git checkout 25a89b5 to get the last known good commit.
git submodule update --init --recursive to make sure everything is still golden after the checkout.
./meteor --help to have the checked out version start
In your project, remove the version info from the .meteor/packages file, as they will likely be incompatible with the ones offered by your checkout.
In your project dir, run /home/yourname/src/remote/meteor/meteor run.

This will run the checked out Meteor version. You may need to do a meteor reset (warning: this clears the local mongo database) or at least clean some of .meteor/local, (e.g, the source maps) for this to work, but this may be unnecessary.

This is quite a lot of effort for a bug which I assume will be resolved in the near future, but I decided to include this info partly in order to be used as documentation for future sourcemap-related issues.