Troubleshoot Magento Issues

Introduction

Magento is one of the leading e-commerce platforms. In this how-to guide, you will learn how Bitnami configures Magento, what the common issues are and how to address them.

Configuration

Bitnami Magento is configured as follows:

Bundled main components

Apache
PHP
MySQL
Git
Memcached
OpenSSL
phpMyAdmin
SQLite
Varnish (TM)

System users

NOTE: This does not apply to Windows installers or non-root installations.

bitnami: SSH login user for cloud images and virtual machines.
daemon: Runs Apache.
mysql: Runs MySQL.
varnish: Runs Varnish (TM).

Permissions and ownership

NOTE: For more information about permission issues, see this guide.

All files in /opt/bitnami/apps/magento/htdocs/ are owned by the daemon system user group. This helps to avoid issues when performing actions using the Magento dashboard.
All subfolders in /opt/bitnami/apps/magento/htdocs/ have 755 using UNIX permissions notation, which means the following:
- Read, write, and execute: daemon user.
- Read and execute: rest of system users.
All files in /opt/bitnami/apps/magento/htdocs/ have 644 using UNIX permission notation, which means:
- Read and write: daemon user.
- Read: rest of system users.

Plugins included

Smtp App for Magento2: Allows you to configure outbound email settings.

Common issues

The following are the most common issues that Bitnami Magento users face:

Permissions: Includes the issues described in this troubleshooting guide. In the case of Magento, most permission issues occur when executing the magento command-line utility as the wrong user.
SSL: Includes the issues described in this troubleshooting guide.
SMTP: Includes the issues described in this troubleshooting guide.
SSH: Includes the issues described in this troubleshooting guide.
Domain name: Includes problems when assigning a domain name.
Changes in Magento configuration files: Configuration issues can break the application, and usually occur by incorrectly changing configuration files such as config.php or env.php.
Infrastructure: Includes issues with the server itself, such as running out of space, performance issues due to suspicious attacks, changes in the IP after rebooting, operating system upgrades, and so on.
Bitnami banner: Issues can occur when removing the Bitnami banner.
Migration and upgrade: Problems can occur when backing up, migrating or upgrading a Magento instance.
Plugins: Includes problems when installing a plugin in Magento. This is usually related to a failure in the Magento readiness check.
Varnish (TM): Includes errors in the Varnish (TM) cache. In the case of Magento, these are usually related to an issue in the Magento application itself.

Troubleshooting checklist

The following checklist covers the majority of cases described above and will help you find and debug most Magento issues.

Are Magento permissions correct?

Several Magento issues such as upgrade, migration or plugin installation occur because of incorrect permissions. Find more information about how to troubleshoot permission errors.

Are Magento cron jobs running?

Magento uses cron jobs for several operations. Some issues in the application are due to executing these jobs incorrectly. To check if they are working correctly, follow these steps:

Log in to the server console. Learn how to connect to the server through SSH.
Execute the following command to obtain the list of cron jobs:
```
  $ sudo cat /etc/crontab
```

Check that the output is similar to the following:

  # /etc/crontab: system-wide crontab
  # Unlike any other crontab you don't have to run the `crontab'
  # command to install the new version when you edit this file
  # and files in /etc/cron.d. These files also have username fields,
  # that none of the other crontabs do.

  SHELL=/bin/sh
  PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin

  17 * * * * root    cd / && run-parts --report /etc/cron.hourly
  25 6 * * * root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.daily )
  47 6 * * 7 root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.weekly )
  52 6 1 * * root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.monthly )
  #

  * * * * * daemon /opt/bitnami/php/bin/php /opt/bitnami/apps/magento/htdocs/bin/magento cron:run -vvv 2>&1 >> /opt/bitnami/apps/magento/htdocs/var/log/magento-cron.log
  * * * * * daemon /opt/bitnami/php/bin/php /opt/bitnami/apps/magento/htdocs/update/cron.php 2>&1 >> /opt/bitnami/apps/magento/htdocs/var/log/magento-update-cron.log
  * * * * * daemon /opt/bitnami/php/bin/php /opt/bitnami/apps/magento/htdocs/bin/magento setup:cron:run -vvv 2>&1 >> /opt/bitnami/apps/magento/htdocs/var/log/magento-setup-cron.log
  35 * * * * bitnami cd /opt/bitnami/stats && ./agent.bin --run -D

Check the following cron job log files for errors:
- /opt/bitnami/apps/magento/htdocs/var/log/magento-cron.log
- /opt/bitnami/apps/magento/htdocs/var/log/magento-setup-cron.log
- /opt/bitnami/apps/magento/htdocs/var/log/magento-update-cron.log
- /opt/bitnami/apps/magento/htdocs/var/log/magento-cron.log

Is the Magento readiness check failing?

If you are trying to upgrade or install a plugin, Magento will perform an application readiness check. If you see a message similar to the following, this indicates that there is something misconfigured in the system:

Permission issues are the most common cause of errors in the readiness check. To check the permissions, follow the steps in this section. If permission issues are not the cause of the errors, see the Magento’s official documentation on troubleshooting readiness check problems.

Did you modify any Magento configuration file?

If you get HTTP 500 errors when accessing your application, check if you have performed any modifications in the /opt/bitnami/apps/magento/htdocs/app/etc/config.php file. Small errors in this configuration file render the application unusable. If you have modified the file, follow these steps:

Try to find any syntax errors in the file.
If you do not find anything suspicious, launch a fresh Magento instance and compare the content of the config.php file in the new instance.
Check that the permissions and ownership are correct (find more details in this section).

Did you modify any Apache configuration file?

If your Magento application is unusable or is having issues loading certain content, check if you have changed any of the following configuration files:

/opt/bitnami/apache/conf/httpd.conf
/opt/bitnami/apache/conf/bitnami/bitnami.conf
/opt/bitnami/apps/magento/conf/httpd-app.conf
/opt/bitnami/apps/magento/conf/htaccess.conf
/opt/bitnami/apps/magento/conf/httpd-prefix.conf
/opt/bitnami/apps/magento/conf/httpd-vhosts.conf

An error modifying these files may break the application configuration. In this case, restore the original Apache configuration. You can do this by launching a fresh Magento instance and comparing the contents of each file.

If you are unable to remove the Bitnami banner (in the bottom right corner), make sure you have done the following:

You have followed the instructions detailed in this guide.
You have checked that the bnconfig command (in the guide above) did not show any error message.
You have executed the command with super-user privileges.

If this does not solve the issue, then open the files below with a text editor and remove their content:

/opt/bitnami/apps/bitnami/banner/conf/banner.conf
/opt/bitnami/apps/bitnami/banner/conf/banner-substitutions.conf

Restart Apache:

$ sudo /opt/bitnami/ctlscript.sh restart apache

Is your installation slow?

By following these steps, you can check if your server is not being suspiciously accessed:

Get the list of top 10 IP addresses that access your site by executing the following command:

  $ tail -n 10000 /opt/bitnami/apache/logs/access_log | awk '{print $1}'| sort | uniq -c | sort -nr | head -n 10

Execute the following command once per IP address in the list. This allows you to check the activity of each one of them (replace the IP_ADDRESS placeholder with the IP address):
```
  $ cat access_log | grep IP_ADDRESS
```
If the IP address is not your internal or external IP and its behavior is suspicious, for example, only accessing one page or only trying to login, it is probably a bot.

If that’s the case, block the address.

Are you getting HTTP 503 errors in Varnish (TM)?

By default, Varnish (TM) is in front of the Magento application, so it can cache requests. If you see the following error, it means that Varnish (TM) failed to communicate with the Magento application:

Error 503 Backend fetch failed, Guru Meditation

This is usually due to some issue in the Magento application rather than an issue in Varnish (TM) itself. To check if Magento is working correctly, follow these steps:

Access the instance using HTTPS (Varnish (TM) does not work with HTTPS).
Check that the application works.

If the application doesn’t work, then the issue is not caused by Varnish (TM) but by Magento. In this case, follow the rest of the troubleshooting instructions in this document to fix the problem.

If the application works, then there is an issue with Varnish (TM). In this case, follow these steps:

Log in to the server console. Learn how to connect to the server through SSH.
Once you have accessed the server, on the terminal window of your local system, execute the following command:
```
  $ sudo varnishlog
```
Check the log provided by the command above to find any possible error.
Check that you did not modify the /opt/bitnami/varnish/etc/varnish/magento.vcl Varnish (TM) script. In the case that you did, try to restore the original content. To do so, you can launch a fresh Magento instance.

Is Magento configured with the correct IP or domain?

Magento requires you to configure a URL in its settings. If you are unable to access your application with errors such as the following, then the instance IP address or domain name may have changed and Magento was not updated with the new URL:

Connection refused

Or:

Connection timeout

In this case, follow these instructions:

Log in to the server console. Learn how to connect to the server through SSH.
Once you have accessed the server, on the terminal window of your local system, execute the following command (replace the IP_OR_DOMAIN placeholder with the IP address or the domain name of the instance):
```
  $ sudo /opt/bitnami/configure_app_domain --domain IP_OR_DOMAIN
```
NOTE: If the result of the previous command shows a command not found error, execute the following command instead:
```
$ sudo /opt/bitnami/apps/magento/bnconfig --machine_hostname IP_OR_DOMAIN
```
Access your instance and check if it works.

Does your instance have swap memory enabled?

Magento recommends having swap memory enabled. Check your current swap space with the free command:

$ free -m
              total        used        free      shared  buff/cache   available
Mem:           3954        1727         774         220        1452        1761
Swap:             0           0           0

From the output, the system has 3954 MB of RAM and 0 MB of swap space.

It’s recommended that swap space should be equal to or bigger than the amount of physical memory (RAM). If you have around 4 GB of RAM, create at least 4 GB of swap space.

Identify a partition for the swap file and create it. If you have an ephemeral partition, that’s ideal:
```
  $ sudo dd if=/dev/zero of=/mnt/swap.0 bs=1M count=4096
  $ sudo mkswap /mnt/swap.0
```

Switch to using the root account and activate the swap area:

  $ sudo su
  $ echo "/mnt/swap.0 swap swap defaults 0 0" >> /etc/fstab
  $ swapon /mnt/swap.0

Check if the swap space was properly enabled with the free command or the command below:
```
  $ sudo swapon -s
```

Useful links

The following resources may be of interest to you:

Varnish is a registered trademark of Varnish Software AB and its affiliates.

Bitnami Premium

Tanzu Application Catalog

Support

Documentation

Kubernetes Tutorials

Kubeacademy

VMware Tanzu Education

Resources

Blog

Careers

VMware Newsroom

Bitnami How-To Guides for VMware Marketplace