Troubleshooting Magento 2 Installations

Overview

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.

CSS/Theme Not Loading

Symptom

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

M2_Static_Content_Missing

Solution

This is when the static content has not properly refreshed after the installation of a module. Deleting contents of the following directories should resolve:
var/view_processed
pub/static/frontend/
pub/static/adminhtml/
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

Symptom

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

Solution

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

Symptom

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.

Solution

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:
    var/view_preprocessed
    pub/static/frontend/
    pub/static/adminhtml/
    pub/static/_requirejs/
    var/generation
    var/cache
    var/page_cache
  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)

Symptom

When running the Compiler the following message is presented:

PHP Fatal error: Class 'PHPUnit_Framework_TestCase' not found

Solution

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/MatrixRate will resolve.

Module already defined

Symptom

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'

Solution

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
    • 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