Local Community

Local-bootstrap.php is triggering a breakpoint when XDebug is enabled

I just wanted to post a solution to this issue in case anyone else is using PHPStorm and experiences it.

What’s happening is that after the latest update to Local (5.7.5+4909) there is now a file that Local is using that is outside the WP installation directory. The default debug settings for PHPStorm have an option for “Force break at first line when a script is outside the project” that is enabled. You will need to disable this option in order to stop the breakpoint from happening on every page load when using XDebug in PHPStorm in the latest version of Local.

The full path to the options in PHPStorm is:

Languages & Frameworks -> PHP -> Debug ->Xdebug section


Nice callout @hereswhatidid!

For backstory, that file that is being included is so Local can make use of the new feature in WordPress core – “Site Environment Types.”

For more information about this feature and how Local implements it, see this help doc:


Hi Gabe,

Thanks for providing the pointer!

Coincidentally, I ran into this as well and took a screenshot at the time. :smiley:

Here it is for a visual representation of what I unchecked:

I’m going to make a follow-up note to see if we can have our Xdebug Add-on handle unchecking these.


Thank you!

I created an account just to say this:

Please revert defining WP_ENVIRONMENT_TYPE. Here are my reasons:

  • As already said by @hereswhatidid, the default option in PhpStorm is to force break when a script is outside of the project. This means that all Local users have to uncheck this option on all their projects. This is not an option IMHO.
  • Having a local-bootstrap.php set as auto_prepend_file will cause the file name in PhpStorms “Debug” dock to always read local-bootstrap.php, regardless of the actual file the breakpoint is in. See this screenshot:
  • It is not possible to quickly switch environments from e.g. development to production for testing purposes if you have a Composer-based setup with WP Starter (which sets multiple constants based on the environment type), because WP_ENVIRONMENT_TYPE will always be set to local.

If you don’t remove this, please make it at least an option (and inactive by default).

BTW, if others wants to to get rid of this, simply comment out the define( 'WP_ENVIRONMENT_TYPE', 'local' ); in /Applications/Local.app/Contents/Resources/extraResources/local-bootstrap.php.

1 Like

Thanks for the great feedback @tyrann0us ! I’ll follow up with the Local team to see if we can get a better way of handling this!

I know that this won’t help with every new site you create, but if you are wanting to stop this behavior from happening, so that you can use WP Starter to manage the environment, you can set auto_prepend_file to none in the php.ini.hbs which should prevent Local from pre-pending the bootstrap.php file.

You’ll have to stop the site and restart it so that the handlebar file is re-compiled for the site.


This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.

I know this topic is closed, but in the interest of connecting topics, there’s a feature request for moving the WP_ENVIRONMENT_TYPE to the wp-config.php file: