How to Troubleshoot 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 to Magento 2.

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

Installing ShipperHQ on Magento 2.4.3 and later

The latest version of Magento 2.4.3 can prevent the installation of some ShipperHQ modules due to an issue with Magento’s composer. This issue affects the following extensions listed in the Magento Marketplace and Packagist:

• ShipperHQ for Magento 2
• WebShopApps MatrixRate
• WebShopApps Product Rate
• Address Autocomplete by ShipperHQ
• Shipping Tracker by ShipperHQ

Use the following steps to install steps to install ShipperHQ and any of the listed extensions above on Magento 2.4.3 and later.

1. Run the following commands from your root Magento installation directory (substitute the module you’re attempting to install for “webshopapps/module-matrixrate“):
   composer remove magento/composer-dependency-version-audit-plugin
composer require webshopapps/module-matrixrate
composer update
php bin/magento setup:upgrade
2. Flush and re-enable the cache if required.
3. Remove generated file content by deleting contents of:
   var/view_processed
pub/static/frontend/
pub/static/adminhtml/
var/generation

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:

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

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 #1

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 #1

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/
generation (or 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

Symptom #2

When running the compiler an external class displays an error similar to:

[RuntimeException]
Source class "\Json" for "JsonMapper" generation does not exist.

Solution #2

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)

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 or ShipperHQ)/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
  • 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.

Fatal error: Uncaught Error: Cannot use object of type stdClass as array

Symptom

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

Solution

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.