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.
On This Page
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:
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
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:
- Flush the cache
- Remove generated file content by deleting contents of:
generation (or var/generation )
- If you are in default or production mode, you will need to recompile your code
When running the compiler an external class displays an error similar to:
[RuntimeException] Source class "\Json" for "JsonMapper" generation does not exist.
This is caused by dependencies not being included in an update/installation.
If you are installing the modules manually each module in the “requires” section of each composer.json file will need to be updated/installed manually. We recommend installing via Composer, per Magento standards, as it is easier to update and maintain.
If you are installing via Composer you may need to denote that the dependencies should be included.
Installing the module (typically not required):
composer require shipperhq/module-shipper --update-with-dependencies
Updating the module:
composer update shipperhq/module-shipper --with-dependencies
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
generation/(with older versions of M2 this was:
- Delete the module from app/code
- Install the module via composer.
“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.
Fatal error: Uncaught Error: Cannot use object of type stdClass as array
When attempting to obtain a rate after upgrading the module-shipper to the latest version you would see an error like this:
/Users/example/Sites/example/project/shipperhq/library-shipper/src/AllowedMethods/Helper.php on line 56
This is caused by a mismatch between the shipper-module and its dependencies. To resolve the shipper-module dependencies must be upgraded to the latest version by following update instructions here.