How to Troubleshoot Magento 2 Installations


In the majority of circumstances, the installation of an extension will proceed without incident. This article covers troubleshooting steps for when there are abnormalities with the installation to Magento 2.

Review the Table of Contents below to find your Issue and instructions to troubleshoot.

CSS/Theme Not Loading


The CSS files or theme are not loading after the installation, often illustrated with the following display on the frontend:



This is when the static content has not properly refreshed after the installation of a module. Deleting contents of the following directories should resolve:
generation/ (with older versions of M2 this was: var/generation )

If that does not resolve on its own you may also need to run the following command from the Magento directory via command line:

php bin/magento setup:static-content:deploy​​

Extension Missing


The extension is not loading in the backend or the frontend, as if the extension did not install at all.


This could be caused due to multiple reasons.

  • If enabled, refresh the Magento cache and the Magento compiler. These must be refreshed for the extension to be registered. If either of these are not enabled they will not need to be enabled for the extension to be registered.
  • If the files were copied over from a ZIP file, ensure that all of the files and directories were copied over successfully.
  • If the files were copied over from a ZIP file, ensure that the installation command was executed after the files have been copied. This is in the form: php bin/magento module:enable <extension_name> – the correct command will be displayed on the respective installation guide.
  • Check to ensure that the files were installed with the correct permissions – the user and group ownership of the files and the permission mask of the files and directories.
    The owner should match the owner of the other files and directories within the installation. The official Magento documentation details how to ensure that the permissions are set correctly.


Class Not Found


A fatal error is displayed similar to:

Fatal error: Class 'Placeholder\text\for\example\purposes' not found in '/path/to/some/file' on line 00.


Ensure that the instance has been cleaned up with the following steps:

  1. Flush the cache
  2. Remove generated file content by deleting contents of:
    generation (or var/generation )
  3. If you are in default or production mode, you will need to recompile your code bin/magento setup:di:compile

TestCase not found (Compiler Error)


When running the Compiler the following message is presented:

PHP Fatal error: Class 'PHPUnit_Framework_TestCase' not found


This is only presented when installing the extension manually via ZIP. We recommend that the extension is installed via Composer to follow Magento 2 standards.

If the extension must be installed via ZIP (not recommended) removing the “test” directory from app/code/(WebShopApps or ShipperHQ)/MatrixRate will resolve.

Module already defined


When installing via Composer you see a message similar to:

Autoload error: Module 'ShipperHQ_Shipper' from '... /app/code/ShipperHQ/Shipper' has been already defined in '... /vendor/shipperhq/module-shipper/src'


This error occurs when a module has been installed via ZIP and the same module is being installed via Composer. We recommend that Composer is used for installations but if this is not feasible the same method (either ZIP or Composer) must be used for all of our modules.

  • Disable the module with the form: php bin/magento module:disable ShipperHQ_<Module> (or WebShopApps_, accordingly)
  • Update Magento with: php bin/magento setup:upgrade
  • Clear cache and re-compile, you will need to refresh the following folders
    • var/cache
    • generation/ (with older versions of M2 this was: var/generation )
    • pub/static/frontend
    • pub/static/adminhtml
    • var/di
  • Delete the module from app/code
  • Install the module via composer.

ShipperHQ Error

“Website not in environment scope. The website does not exist in the environment scope”

This is due to ShipperHQ and Magento looking at different scopes. You’ll want to ensure the scope in the top right of your ShipperHQ account matches the scope shown under ShipperHQ Configuration.

set scope in magento

Set Scope in ShipperHQ

Was this doc helpful?