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

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.

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 bitnami system user and the daemon group. This helps to avoid issues when uploading files to the stack.
  • All subfolders in /opt/bitnami/apps/magento/htdocs/ except var and vendor have 755 using UNIX permissions notation, which means the following:
    • Read, write, and execute: bitnami user.
    • Read and execute: rest of system users.
  • The subfolders /opt/bitnami/apps/magento/htdocs/var, /opt/bitnami/apps/magento/htdocs/vendor and /opt/bitnami/apps/magento/htdocs/pub/media have 775 using UNIX permissions notation, which means the following:
    • Read, write, and execute: bitnami user and daemon group.
    • Read and execute: rest of system users.
  • All files in /opt/bitnami/apps/magento/htdocs/ except those located in app/etc, vendor and cache have 644 using UNIX permission notation, which means:
    • Read and write: bitnami user.
    • Read: rest of system users.
  • Uploaded files in /opt/bitnami/apps/magento/htdocs/pub/media using the Magento admin interface are owned by the bitnami user and the daemon group and have 644 using UNIX permission notation, which means:
    • Read and write: bitnami user and group daemon.
    • Read: rest of system users.
  • All files in /opt/bitnami/apps/magento/htdocs/app/etc, /opt/bitnami/apps/magento/htdocs/vendor have 664 using UNIX permission notation, which means:
    • Read and write: bitnami user and daemon group.
    • Read: rest of system users.
  • All folders located in /opt/bitnami/apps/magento/htdocs/cache have 777 using UNIX permission notation, which means:
    • Read and write and execute: all users.
  • All files located in /opt/bitnami/apps/magento/htdocs/cache have 660 using UNIX permission notation, which means:
    • Read and write: bitnami user and daemon group.
    • No operation allowed: rest of system users.

Plugins included

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: Includes errors in the Varnish 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. To address this, the stack includes a script that sets the permissions of the installation directory properly.

$ /opt/bitnami/apps/magento/scripts/fixPermissions.sh

You can find more permission troubleshooting actions in this guide.

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 your instance through SSH following these instructions.
  • Execute the following command to obtain the list of cron jobs:

      $ sudo su bitnami -c "crontab -l"
    
  • Check that the output is similar to the following:

      */1 * * * * /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 #magento-cron
      */1 * * * * /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 #magento-update-cron
      */1 * * * * /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 #magento-setup-cron
      */1 * * * * /opt/bitnami/apps/magento/scripts/fixPermissions.sh unattended 2>&1 >> /opt/bitnami/apps/magento/htdocs/var/log/magento-cron.log #magento-permissions
    
  • 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:

Magento readiness check failure

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/apache2/conf/httpd.conf
  • /opt/bitnami/apache2/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.

You can't remove the Bitnami banner?

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?

If you are experiencing performance issues in your application, follow the instructions shown in this guide. In addition, 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/apache2/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 by following this guide.

Are you getting HTTP 503 errors in Varnish?

By default, Varnish is in front of the Magento application, so it can cache requests. If you see the following error, it means that Varnish 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 itself. To check if Magento is working correctly, follow these steps:

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

If the application doesn't work, then the issue is not caused by Varnish 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. In this case, follow these steps:

  • Log in to your instance through SSH following this guide.
  • 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 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 your instance through SSH following this guide.
  • 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/apps/magento/bnconfig --machine-hostname IP_OR_DOMAIN
    
  • Access your instance and check if it works.

The following resources may be of interest to you:

aws

Bitnami Documentation