How to Troubleshoot Magento 2 Installations

• Overview
• Installing ShipperHQ on Magento 2.4.3 and Later
• CSS/Theme Not Loading
• Class Not Found
• TestCase Not Found (Compiler Error)
• Module Already Defined
• ShipperHQ Error
• Fatal Error: Uncaught Error: Cannot Use Object of Type stdClass as Array

Overview

Most of the time, installing an extension goes smoothly. However, if you run into issues with your Magento 2 installation, this guide will help you troubleshoot. Check the Table of Contents for your specific issue and follow the instructions to resolve it. 

Installing ShipperHQ on Magento 2.4.3 and Later

Magento 2.4.3 might block the installation of certain ShipperHQ modules because of a composer issue. Affected extensions include:

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

Follow these steps to install ShipperHQ or any listed extensions on Magento 2.4.3 and later:

1. Run the following commands from your root Magento installation directory (replace "[code]webshopapps/module-matrixrate[/code]" with the module you're installing):

    

   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 needed.

3. Delete files in these directories:

    

   • var/view_processed
   • pub/static/frontend/
   • pub/static/adminhtml/
   • var/generation

CSS/Theme Not Loading

Symptom: The CSS files or theme are not loading, causing display issues on the frontend.

Solution: Static content hasn't been refreshed after module installation. Clear these directories:

• var/view_processed
• pub/static/frontend/
• pub/static/adminhtml/
• generation/ (or var/generation for older versions)

If issues persist, run this command from the Magento directory:

php bin/magento setup:static-content:deploy

### Extension Missing

**Symptom**: The extension seems not to load at all.

**Solution**: This could be due to several reasons:

- Refresh the Magento cache and compiler if enabled.
- If files were copied from a ZIP, ensure all files and directories are successfully copied.
- Ensure the installation command is executed post-copy. The form is:

 ```sh
 php bin/magento module:enable <extension_name>

• Check file permissions and ownership. See Magento documentation.

Class Not Found

Symptom #1: You see a fatal error indicating a missing class.

Solution #1: Clean up the instance:

1. Flush the cache.

2. Delete content from these directories:

   • var/view_preprocessed
   • pub/static/frontend/
   • pub/static/adminhtml/
   • pub/static/_requirejs/
   • generation or var/generation
   • var/cache
   • var/page_cache

3. Recompile the code in default or production mode:

   bin/magento setup:di:compile
   

Symptom #2: A runtime error appears in the compiler due to a missing class.

Solution #2: Manually install missing dependencies or use Composer for easier updates:

composer require shipperhq/module-shipper --update-with-dependencies
composer update shipperhq/module-shipper --with-dependencies

### TestCase Not Found (Compiler Error)

**Symptom**: Compiler error referencing 'PHPUnit_Framework_TestCase'.

**Solution**: Recommended installation via Composer. If using ZIP (not recommended), delete the "test" directory from:

- `app/code/(WebShopApps or ShipperHQ)/MatrixRate`
### Module Already Defined

**Symptom**: The error suggests a module is already defined.

**Solution**: Occurs when a module is installed via ZIP and Composer. Ensure the consistent method across modules:

- Disable the module:

 ```sh
 php bin/magento module:disable ShipperHQ_<Module>

• Update Magento:

  php bin/magento setup:upgrade
  

• Clear cache and re-compile. Refresh these folders:

  • var/cache
  • generation/ or var/generation
  • pub/static/frontend
  • pub/static/adminhtml
  • var/di

• fatal-error-uncaught-error-cannot-use-object-ofDelete the module from app/code.

• Install the module via Composer.

ShipperHQ Error

Symptom: "Website not in environment scope." Ensure the ShipperHQ account scope matches the one in ShipperHQ Configuration.

Fatal Error: Uncaught Error: Cannot Use Object of Type stdClass as Array

Symptom: Error when obtaining a rate after updating the module-shipper.

Solution: Ensure dependencies are updated to match the shipper-module by following update instructions here.