How to Troubleshoot Magento 2 Installations

Table of Contents

• Overview
• Installing ShipperHQ on Magento 2.4.3 and Later
• CSS/Theme Not Loading
• Extension Missing
• 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

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