Fix common Magento 2 errors

Most Magento 2 problems come from a handful of causes: static files, caches, indexers, cron, the search engine and file permissions. This guide lists the common Magento 2 errors and the commands that fix them. Run every command from the Magento root as the file owner, never as root.

Before you start

• SSH access to the server.
• Check the logs first: var/log/system.log, var/log/exception.log and var/report/.
• Take a backup of files and database before bigger changes. See back up with mysqldump.

Pages load without CSS or JavaScript

Static content is missing or out of date, usually after an upgrade or a theme change in production mode.

php bin/magento setup:static-content:deploy -f && php bin/magento cache:flush

If files still return 404, check that the web server's root points to pub/ and that pub/static/.htaccess (Apache/LiteSpeed) or the Nginx sample config is in place.

One or more indexers are invalid

php bin/magento indexer:status

php bin/magento indexer:reindex

If indexers keep going invalid, cron is not running. Set the indexers to Update by Schedule so cron handles them.

Cron is not running

Check with crontab -l as the Magento user. If the entries are missing, run:

php bin/magento cron:install

Then confirm that jobs run: the cron_schedule table should fill with success rows within a few minutes.

Could not validate a connection to OpenSearch

Magento 2.4 needs a search engine. Check that the service is up and reachable:

curl -s http://localhost:9200

If it does not answer, start it (sudo systemctl start opensearch) and check its log. A small VPS often kills OpenSearch for lack of memory; see fix the OOM killer. Then update the host in Stores → Configuration → Catalog → Catalog Search or with bin/magento config:set.

Allowed memory size exhausted

Compiling and deploying need a lot of memory. Run the command with a higher limit:

php -d memory_limit=-1 bin/magento setup:di:compile

For the website itself, set memory_limit to at least 756M in PHP-FPM. Background is in fix allowed memory size exhausted.

Permission denied or files cannot be written

Set Magento's recommended permissions from the Magento root:

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 {} +

Make sure the PHP-FPM user and the CLI user are in the same group. Running bin/magento as root creates root-owned files that break the site.

Site stuck in maintenance mode

php bin/magento maintenance:disable

If that fails, delete var/.maintenance.flag.

There has been an error processing your request

The page shows a report number. Open var/report/<number> to see the real exception. Common causes are a broken third-party module, which you can disable with bin/magento module:disable Vendor_Module, and stale generated code, which you can clear with rm -rf generated/code/* followed by setup:di:compile.

FAQ

How do I enable developer mode to see errors?

Run php bin/magento deploy:mode:set developer on staging only. In production, read var/report and var/log instead.

Why is my Magento store so slow?

Usually the site has no full-page cache, uses the file cache instead of Redis, or has indexers on save. Use Varnish or LiteSpeed, move caching to Redis, and run indexers by schedule.

What should I run after installing a module?

setup:upgrade, then setup:di:compile, then setup:static-content:deploy in production mode, and finally cache:flush.