Magento 2.x Troubleshooting Guide

The developers make every effort to ensure their Magento extensions are stable, reliable, and well-tested. However, due to the highly-customizable nature of Magento they cannot anticipate every possible configuration and so incompatibilities may arise. This guide gives an overview of the most common issues are found on client’s sites and how to resolve them.

The purpose of this document is to help the magento2 users in solving the commonly faced issues while installation and usage of Magento 2.x Extensions.

The most common methods of troubleshooting are as follows:

• Refreshing the Cache
• Reindexing the Magento
• Solving 404 error on System Configuration
• Permission issues on new extension
• Disable Maintenance Mode if your Extension is not installed successfully
• Disable the newly installed Extension if your Magento store stops working or throws fatal error
• View list of extensions and Disable/Enable installed extensions
• Fixing Permission error after running php bin magento/bin setup:upgrade command
• Setting Deploy mode: Developer to see exact errors
• Solving error while deploying sample data
• Fixing errors while static-content deploy

Refreshing the Cache

After installing the extension on Magento, if the installed Extension is not visible or is not working properly then you can try Refreshing the Cache from Magento Admin. You can do it via ssh/terminal (CLI) or can do it from admin panel.

1. Via SSH/Terminal (CLI)

Run this command into CLI:

php bin/magento cache:clean

If it doesn’t solves the problem, run:

php bin/magento cache:flush

Note: You might need to set correct permission to the var/ pub/ and generated/ directories after completion of the above commands.

2. Via Admin Panel

To refresh the cache from admin panel, follow these steps:

1. Log into Magento Store Admin Panel
2. Navigate to System ⇒ Cache Management. Now select all the cache types in the list, choosing the refresh option in the drop down menu , and finally clicking Submit.

<figcaption class="wp-element-caption">

Refreshing cache from Admin Panel

Reindexing the Magento

You can also try Reindexing the Magento, if you are having problem with your newly Installed Extension. It can be done by running this command in CLI:

php bin/magento indexer:reindex

Make sure that all indexers are reindexed and the output of the command looks like:

Category Products index has been rebuilt successfully in <time>
Product Categories index has been rebuilt successfully in <time>
Product Price index has been rebuilt successfully in <time>
Product EAV index has been rebuilt successfully in <time>
Stock index has been rebuilt successfully in <time>
Catalog Rule Product index has been rebuilt successfully in <time>
Catalog Product Rule index has been rebuilt successfully in <time>
Catalog Search index has been rebuilt successfully in <time>

Source: Magento DevDocs

Solving 404 error on Store Configuration

After installing your Extension, if you got 404 error on Store ⇒ Configuration, then it may be the problem of Magento Session/Registry, you can solve this issue just by Logging Out of Magento admin and Logging In again.

Permission issues on new extension

Sometimes the installation will fail because Magento doesn’t have sufficient permissions to write to the necessary web server directories. There are multiple ways to fix this.

1. Easiest way but not secure: Just give the 777 permission to your Extension folders and try uploading again.
2. Linux Permissions: Your apache user:group in linux and the folder permissions of your magento should match. e.g if your cPanel/ftp username/ssh user is “mjoy”. You need to check which group this user belongs to. Suppose “mjoy” user belongs to group “company”. In this case add “www-data” or “apache” group to “company” group as well. This is a bit complex to solve and require good knowledge of linux permission system.

Disable Maintenance Mode if your Extension is not installed successfully

The solution of this problem is simple. You may choose any of the below methods:

1. Using CLI

You need to run following command to disable maintenance mode:

php bin/magento maintenance:disable

Similarly, if you need to enable the maintenance mode, you may run:

php bin/magento maintenance:enable

2. Using FTP/File System

Access FTP into your remote website directory where your Magento files reside.

Find & delete the file named var/.maintenance.flag.

Your site should now work normally.

Disable the newly installed Extension (module/plugin) if your Magento store stops working or throws fatal error

If you are getting any fatal error and getting any exception after you have installed new extension. Just disable the new extension. You can do that by running a command from terminal:

php bin/magento module:disable ExtensionVendor_ModuleName

After doing this clear the cache and try to load your store again.

You can use this command to get the list of all extensions:

php bin/magento module:status

View list of extensions and Disable/Enable installed extensions

Some time after installing extension our extension does not appear in our store so to solve this issue we have to check few things that is given below:

1. Check list of extension installed in your store you can do that by following command in your terminal

php bin/magento module:status

2. You will get list of all extension check your extension is there or not if not then you have to type another command to enable you extension:

php bin/magento module:enable ExtensionVendor_ModuleName

After doing this you will get to see your extension on your store.

Fixing Permission error after running “php bin magento/bin setup:upgrade” or “php bin magento/bin setup:di:compile” command

Once you have run upgrade command then if you will not give permission then you will get few errors.

In order to resolve it you have to run few commands that will give proper permission commands are as:

find var generated vendor pub/static pub/media app/etc -type f -exec chmod g+w {} +
find var generated vendor pub/static pub/media app/etc -type d -exec chmod g+ws {} +
chown -R :www-data . # Ubuntu

You might need to run these commands too:

sudo chmod -R 777 var/
sudo chmod -R 777 pub/
sudo chmod -R 777 generated/

After completion of the above steps, permission issue will be resolved.

Setting Deploy mode:developer to see exact errors

Magento comes with 3 different modes out of the box (developer, default and production). In order to check exact error you have to switch to developer mode for that write following command:

php bin/magento deploy:mode:set developer

Now it will be set to developer mode and you can check the exact error.

Note: To know more about the deploy modes, click here.

Solving error while deploying sample data

Some time when we are deploying sample data we get error in that case we can resolve the issue by the following command:

composer config repositories.0 composer https://repo.magento.com

Your issue will be resolved.

Fixing errors while static-content deploy

We get error like this check Installation File Permissions when we do static-content-deploy. To debug this, follow these steps:

Open setup/src/Magento/Setup/Model/FilePermissions.php

Goto line 143 in method checkRecursiveDirectories()

Add the lines var_dump($subDirectory); var_dump($subDirectory->isWritable());

Re-run:

php bin/magento setup:upgrade

Now you’ll see what is really wrong, and you can fix it.