During the process of installing and setting up Magento 2, I ran into some issues and thought I would detail what was happening in my case. For information on how to install Magento 2, take a look at the Magento docs or this guide.

Before you start:

I set up a virtual machine with PuPHPet (config example). In the example, I use NFS file syncing and Parallels to enhance performance since I have found Magento 2 to run slowly in a development environment.

Regardless of the environment you are using, it is important to confirm that your PHP max_execution_time and memory_limit settings are correct. At time of writing those values should be: max_execution_time = 1800 and memory_limit = 512M.

You can check what they are currently set to by creating a PHP file with phpinfo() in it and visiting that file, or run php -i | grep max_execution and php -i | grep memory_limit. Don't forget that your CLI version of PHP might be different than what is running the site, which could make the output of that command not relevant.

Specific Errors:

During an installation from Composer (details), these were some of the problems that I ran into.

TransportException: file could not be downloaded

When running the composer create-project command from my host (which runs PHP 5.5 by default), I got this error message:

The "https://repo.magento.com/packages.json" file could not be downloaded: 
Failed to enable crypto failed to open stream: operation failed

My machine is running PHP 5.5.30 from the command line and Composer and Magento don't like that. The reason is that OS X comes bundled with an older version of PHP. The older versions of PHP don't support the TLS version required by Magento.


  1. Run the command from your virtual machine as it should have an upgraded version of PHP and Composer on there.
  2. (For OS X) Or, you can download PHP 7 and Composer into the site directory.

Missing PHP Packages

Magento 2 requires a number of PHP packages. When I started up a VM (with PuPHPet), I hadn't included those. As a result, I needed to find and add all the necessary packages to my config.yaml file and re-provision the machine. This may seem like a no-brainer, but don't skip the step.

Error updating Composer

When attempting to run composer update, I received an error that stated that I needed to authenticate with repo.magento.com.

Login to the Magento Marketplace and create a new access key. Now, when it prompts you for your username and password, enter the public key as the username and private key as the password.

Installation Exception - SessionHandler::read()

While running the installer from the browser, it made it about 65% of the way through and then failed with an exception like this:

exception 'Exception' with message 'Warning: SessionHandler::read():
open(..) failed: No such file or directory (2) ../magento2/lib/internal/Magento/Framework/Session/SaveHandler.php on line 74' 
in ../magento2/lib/internal/Magento/Framework/App/ErrorHandler.php:67

I attempted to adjust the permissions of the vendor folder, but ended up re-installing the Composer dependencies by removing the vendor/ folder and deleting composer.lock. After clearing those, I re-ran composer install.

Error 503 Service Temporarily Unavailable

This occurred because there was an error during the installation of Magento. The installer had created a .maintenance.flag file and displayed a 503 error because that file existed.

Remove the file from var/ folder.

PHP Exception being saved to reports

Here's an example:

Magento_Wishlist data: current version - none, required version - 2.0.0
Magento_WishlistSampleData data: current version - none, required version - 2.0.0";i:1;s:2594:"#0 [internal function]: Magento\Framework\Module\Plugin\DbStatusValidator->aroundDispatch(Object(Magento\Framework\App\FrontController\Interceptor), Object(Closure), Object(Magento\Framework\App\Request\Http))
#1 /var/www/magentotwo/vendor/magento/framework/Interception/Chain/Chain.php(67): call_user_func_array(Array, Array)
#2 /var/www/magentotwo/vendor/magento/framework/Interception/Chain/Chain.php(63): Magento\Framework\Interception\Chain\Chain->invokeNext('Magento\\Framewo...', 'dispatch', Object(Magento\Framework\App\FrontController\Interceptor), Array, 'front-controlle...')
#3 /var/www/magentotwo/vendor/magento/module-page-cache/Model/App/FrontController/VarnishPlugin.php(55): Magento\Framework\Interception\Chain\Chain->Magento\Framework\Interception\Chain\{closure}(Object(Magento\Framework\App\Request\Http))
#4 [internal function]: Magento\PageCache\Model\App\FrontController\VarnishPlugin->aroundDispatch(Object(Magento\Framework\App\FrontController\Interceptor), Object(Closure), Object(Magento\Framework\App\Request\Http))
#5 /var/www/magentotwo/vendor/magento/framework/Interception/Chain/Chain.php(67): call_user_func_array(Array, Array)
#6 /var/www/magentotwo/vendor/magento/framework/Interception/Interceptor.php(136): Magento\Framework\Interception\Chain\Chain->invokeNext('Magento\\Framewo...', 'dispatch', Object(Magento\Framework\App\FrontController\Interceptor), Array, 'front-controlle...')
#7 /var/www/magentotwo/vendor/magento/module-page-cache/Model/App/FrontController/BuiltinPlugin.php(68): Magento\Framework\App\FrontController\Interceptor->Magento\Framework\Interception\{closure}(Object(Magento\Framework\App\Request\Http))
#8 [internal function]: Magento\PageCache\Model\App\FrontController\BuiltinPlugin->aroundDispatch(Object(Magento\Framework\App\FrontController\Interceptor), Object(Closure), Object(Magento\Framework\App\Request\Http))
#9 /var/www/magentotwo/vendor/magento/framework/Interception/Interceptor.php(140): call_user_func_array(Array, Array)
#10 /var/www/magentotwo/var/generation/Magento/Framework/App/FrontController/Interceptor.php(26): Magento\Framework\App\FrontController\Interceptor->___callPlugins('dispatch', Array, Array)
#11 /var/www/magentotwo/vendor/magento/framework/App/Http.php(115): Magento\Framework\App\FrontController\Interceptor->dispatch(Object(Magento\Framework\App\Request\Http))
#12 /var/www/magentotwo/vendor/magento/framework/App/Bootstrap.php(258): Magento\Framework\App\Http->launch()
#13 /var/www/magentotwo/index.php(39): Magento\Framework\App\Bootstrap->run(Object(Magento\Framework\App\Http))
#14 {main}";s:3:"url";s:1:"/";s:11:"script_name";s:10:"/index.php";}

I believe that exception was related to a previous, and failed, install of Magento. My solution was to re-setup Magento. Thanks to the developers at Magento, it's easy to reset the installation: php bin/magento setup:uninstall. Note that running that command doesn't actually remove Magento like you would if you were to delete the directory. It leaves the core files in place and removes anything that had been installed.

After successfully uninstalling, I went to the site again and ran through the installer via the browser.

After Installation:

Here are a few tips for after you finish the installation:

  1. Make sure to set the store to developer mode: php bin/magento deploy:mode:set developer.
  2. Generate the catalog of URNs php bin/magento dev:urn-catalog:generate
  3. While developing a theme, this command creates symlinks for static assets (fast) instead of actually compiling them all (slow): php bin/magento dev:source-theme:deploy.

Did I miss anything? Leave a comment below.

SwiftOtter, Inc.
It relates to Magento 2, Front end development, Back end development and Developer Environment.
Jesse Maxwell - Front end developer at Swift Otter

Front end developer at SwiftOtter - @bassplayer_7