How to Fix Magento 500 Internal Server Error

A 500 Internal Server Error is one of the most common and frustrating problems that can affect a Magento store. Instead of loading the storefront or Admin Panel, visitors may see a generic server error page.

The message itself does not identify the real cause. A Magento 500 error can be triggered by PHP incompatibility, incorrect file permissions, broken extensions, corrupted generated files, Composer problems, insufficient memory, database issues, or web-server configuration errors.

The good news is that most Magento 500 errors can be diagnosed without reinstalling Magento.

This guide explains how to identify the cause and fix a Magento 500 Internal Server Error safely.

---

What Does a Magento 500 Internal Server Error Mean?

An HTTP 500 error means that the server encountered an unexpected condition while processing the request.

In Magento, the actual problem may be somewhere in the application stack:

Browser
   ↓
Web Server
   ↓
PHP / PHP-FPM
   ↓
Magento
   ↓
Extensions / Theme
   ↓
Database / Redis / Search

Any failure in this chain can result in a 500 response.

For example, a recently installed extension might contain incompatible PHP code. The web server then receives a fatal PHP error and returns:

500 Internal Server Error

Therefore, the first goal is not to “fix error 500” directly, but to determine what caused the server to return it.

---

Common Causes of Magento 500 Errors

A Magento 500 error can be caused by:

• PHP version incompatibility
• Missing PHP extensions
• PHP memory exhaustion
• Incorrect file permissions
• Incorrect file ownership
• Broken Magento extensions
• Invalid custom PHP code
• Corrupted generated classes
• Missing Composer dependencies
• Incorrect env.php
• Database connection problems
• Broken .htaccess configuration
• Incorrect Nginx or Apache configuration
• Failed Magento upgrade
• Failed static-content deployment
• Full disk space
• PHP-FPM failure
• Redis problems
• OpenSearch or Elasticsearch problems
• Incorrect server configuration

The fastest solution is to identify which category applies to your installation.

---

Step 1: Back Up Magento Before Troubleshooting

Before making major changes, create a backup if the server is still accessible.

Back up your Magento files:

tar -czf magento-files-backup.tar.gz public_html/

Back up the database:

mysqldump -u database_user -p database_name > magento-database.sql

Compress the database backup:

gzip magento-database.sql

At minimum, preserve:

app/etc/env.php
app/etc/config.php
composer.json
composer.lock
pub/media/

Do not begin deleting files or changing the database until you have a recoverable copy.

---

Step 2: Check Magento Logs First

Magento logs are usually the best starting point.

From your Magento root directory:

cd /path/to/magento

Check the log directory:

ls -lah var/log/

Common files include:

var/log/system.log
var/log/exception.log

View recent errors:

tail -n 100 var/log/system.log

and:

tail -n 100 var/log/exception.log

For live monitoring:

tail -f var/log/exception.log

Look for messages containing:

PHP Fatal error
Uncaught Error
Class not found
Allowed memory size exhausted
SQLSTATE
Permission denied
Call to undefined function

The first meaningful error is often more useful than the final 500 error message.

---

Step 3: Check the Web-Server Error Log

If Magento logs do not reveal the problem, check your web-server logs.

A server-level PHP error may occur before Magento can write anything to its own logs.

Depending on your server, inspect:

Apache

The error log may be located in a server-specific Apache log directory.

Nginx

A common location is:

tail -n 100 /var/log/nginx/error.log

PHP-FPM

PHP-FPM also has its own error logs depending on the PHP version and server configuration.

Look for:

PHP Fatal error
Maximum execution time exceeded
Allowed memory size exhausted
Primary script unknown
Permission denied
File not found
Connection refused

The exact log location varies by Linux distribution, hosting panel, and PHP configuration.

---

Step 4: Check the PHP Version

A PHP version mismatch is one of the most important things to check after:

• Magento upgrades
• PHP upgrades
• Server migrations
• Hosting changes
• Extension installations

Check the CLI version:

php -v

Then verify the PHP version actually used by the website.

This distinction is important because:

CLI PHP ≠ PHP-FPM PHP

Your command-line environment could be using one PHP version while Apache or Nginx uses another.

Make sure the PHP version is compatible with your installed Magento version and extensions.

---

Step 5: Check Required PHP Extensions

Run:

php -m

Look for the extensions required by your Magento version.

Common Magento-related extensions include:

bcmath
curl
dom
fileinfo
gd
intl
mbstring
openssl
pdo_mysql
simplexml
soap
xml
xsl
zip

The exact requirements depend on the Magento version and installed packages.

A missing extension can cause errors such as:

Class not found
Call to undefined function
Unable to load dynamic library

Install missing extensions through your server’s package manager or hosting control panel, then restart the appropriate PHP-FPM/web-server service if required.

---

Step 6: Check PHP Memory Limit

Magento can generate a 500 error when PHP runs out of memory.

Check the current CLI memory limit:

php -i | grep memory_limit

You may see:

memory_limit => 512M => 512M

The PHP-FPM/web-server value can be different, so verify the effective value used by the website as well.

For Magento operations such as compilation, static-content deployment, and large catalog processing, insufficient memory can cause failures.

If necessary, adjust the appropriate PHP configuration:

memory_limit = 512M

The exact value should be based on your Magento version, extensions, workload, and available server RAM.

After changing PHP-FPM configuration, restart or reload PHP-FPM if your server requires it.

---

Step 7: Check Disk Space

A full disk can produce seemingly unrelated Magento errors.

Run:

df -h

Also check inode availability:

df -i

If either disk space or inodes are exhausted, Magento may be unable to:

• Write logs
• Create cache files
• Generate code
• Upload media
• Create sessions
• Compile dependencies

Find large directories:

du -sh * | sort -h

Free sufficient space and then retry the Magento operation.

---

Step 8: Check File Ownership and Permissions

Incorrect ownership is common after:

• Moving Magento between servers
• Restoring backups
• Running Composer as root
• Uploading files through FTP
• Manually copying files

Check ownership:

ls -lah

Magento should be owned according to your server’s PHP-FPM and web-server configuration.

Pay particular attention to writable directories such as:

var/
generated/
pub/static/
pub/media/
app/etc/

Do not use:

chmod -R 777 .

as a general solution.

It may hide permission problems temporarily while creating serious security risks.

---

Step 9: Test the env.php Configuration

Magento’s environment configuration is stored in:

app/etc/env.php

Check that the file exists:

ls -l app/etc/env.php

Check PHP syntax:

php -l app/etc/env.php

You should see:

No syntax errors detected in app/etc/env.php

If you recently changed:

• Database credentials
• Redis settings
• Search configuration
• Cache configuration
• Cryptographic settings

review those changes carefully.

Do not publish the contents of env.php, because it contains sensitive configuration data.

---

Step 10: Test the Database Connection

If the logs contain database errors, test the connection directly.

For example:

mysql -u database_user -p database_name

If the connection succeeds, run:

SHOW TABLES;

If it fails, verify:

• Database hostname
• Database name
• Username
• Password
• MySQL/MariaDB status
• User permissions
• Firewall rules

A typical Magento database error might look like:

SQLSTATE[HY000] [1045] Access denied for user

This indicates that Magento cannot authenticate with the database using its configured credentials.

---

Step 11: Clear Magento Cache

If Magento CLI is working, clear the cache:

php bin/magento cache:flush

You can check the cache status first:

php bin/magento cache:status

A stale or inconsistent cache can sometimes cause errors after configuration or deployment changes.

---

Step 12: Clear Generated Magento Code

Generated classes can become invalid after an extension, PHP, or Magento change.

Remove generated code:

rm -rf generated/code/*
rm -rf generated/metadata/*

Then compile Magento:

php bin/magento setup:di:compile

If compilation fails, do not ignore the output.

The compilation error often identifies:

• Broken extension
• Incompatible PHP code
• Missing class
• Missing dependency
• Invalid custom code

---

Step 13: Regenerate Static Content

If the 500 error occurs alongside missing CSS or JavaScript, regenerate static content.

Run:

rm -rf pub/static/_cache
rm -rf var/view_preprocessed/*

Then:

php bin/magento setup:static-content:deploy -f

Flush cache:

php bin/magento cache:flush

If the deployment command fails, investigate its first meaningful error instead of repeatedly running the command.

---

Step 14: Check Composer Dependencies

Magento relies heavily on Composer packages.

Validate the Composer configuration:

composer validate

If the vendor directory is incomplete, run:

composer install

For a production environment:

composer install --no-dev

If a valid composer.lock file exists, composer install is generally preferred because it installs the locked dependency versions.

Avoid using:

composer update

as a generic 500-error fix.

A Composer update can change multiple package versions and potentially create additional compatibility problems.

---

Step 15: Check Recently Installed Extensions

If the 500 error appeared immediately after installing or updating an extension, that extension is a strong suspect.

List Magento modules:

php bin/magento module:status

If you know the affected module, you may be able to disable it:

php bin/magento module:disable Vendor_Module

Then run:

php bin/magento setup:upgrade
php bin/magento cache:flush

Do not disable modules randomly. Some modules depend on others, and disabling a core or required dependency can make the situation worse.

---

Step 16: Check Custom Theme Code

A custom theme can cause a 500 error if it contains incompatible PHP or template code.

If the problem appears only on the storefront, investigate recent theme changes.

Look for:

• PHP errors
• Invalid templates
• Missing layout files
• Incompatible customizations
• Missing classes
• Incorrect file permissions

If the Admin Panel works but the storefront does not, theme and frontend module issues become stronger candidates.

---

Step 17: Check .htaccess Configuration

Apache-based Magento installations commonly use .htaccess files.

A modified or corrupted .htaccess can result in a 500 error.

Check whether .htaccess was recently changed.

Look for invalid directives or directives unsupported by the current Apache configuration.

Do not blindly replace the file with a random version from the Internet. Compare it against the correct .htaccess for your Magento version and installation.

If the error is:

Internal Server Error

and the Apache error log mentions:

Invalid command

or:

.htaccess syntax error

the web-server configuration should be investigated first.

---

Step 18: Check Nginx or Apache Configuration

A Magento application can be healthy while the web server is incorrectly configured.

Check your web-server configuration after:

• Server migration
• PHP-FPM changes
• Domain changes
• SSL changes
• Magento upgrades

For Nginx, test the configuration:

nginx -t

For Apache, depending on the server:

apachectl configtest

A successful configuration test does not guarantee Magento is configured correctly, but it can identify obvious web-server syntax problems.

---

Step 19: Check PHP-FPM

If the web server is unable to communicate with PHP-FPM, Magento requests may return 500 or 502 errors.

Check the PHP-FPM service status using your system’s service name.

For example:

systemctl status php-fpm

On systems with version-specific services, the service may instead look similar to:

systemctl status php8.2-fpm

The exact service name varies by operating system and PHP installation.

Look for:

• Service stopped
• Configuration errors
• Worker crashes
• Socket problems
• Permission errors
• Memory exhaustion

Restart PHP-FPM only after checking the cause, especially on a busy production server.

---

Step 20: Check Redis

If Magento uses Redis for caching or sessions, an unavailable Redis service can cause application problems.

Test Redis:

redis-cli ping

A working service normally responds:

PONG

Check the Redis configuration in:

app/etc/env.php

Verify:

• Host
• Port
• Password
• Database number
• Socket configuration

If Redis was moved to another server, make sure the Magento configuration was updated accordingly.

---

Step 21: Check OpenSearch or Elasticsearch

Magento search depends on the configured search engine.

If the 500 error started after a server migration or search configuration change, verify that the required service is available.

Check Magento’s configuration:

grep -n -E "elasticsearch|opensearch" app/etc/env.php

Then check the service and connectivity.

A search-engine problem may not always produce a 500 error across the entire store, but it can cause failures on catalog or search-related pages.

---

Step 22: Check Indexers

Check Magento indexer status:

php bin/magento indexer:status

If indexes are invalid or stuck, run:

php bin/magento indexer:reindex

Then check again:

php bin/magento indexer:status

If the reindex command itself fails, inspect the error rather than repeatedly running it.

---

Step 23: Check Cron Jobs

Magento depends on scheduled tasks for many background operations.

Run:

php bin/magento cron:run

Then verify your server’s actual cron configuration.

Cron problems usually do not cause every type of 500 error, but they can contribute to:

• Stale indexes
• Scheduled updates not running
• Email problems
• Catalog rule issues
• Background processing failures

---

Step 24: Check Maintenance Mode

Magento may show a server error or unavailable page if maintenance mode is active or incomplete.

Check:

php bin/magento maintenance:status

If the maintenance period is finished:

php bin/magento maintenance:disable

Then flush the cache:

php bin/magento cache:flush

If the CLI is unavailable, investigate the underlying PHP/application problem rather than deleting Magento maintenance files blindly.

---

Step 25: Check for a Failed Magento Upgrade

If the 500 error appeared immediately after upgrading Magento, examine:

composer.json
composer.lock

and check:

php bin/magento --version

Review the Composer and Magento upgrade output.

A failed upgrade may leave:

• Incomplete dependencies
• Incompatible extensions
• Generated-code problems
• Database schema changes
• Static-content problems

If a reliable pre-upgrade backup exists, restoring the application and database to a known-good state may be safer than making many unrelated changes.

---

Step 26: Check for a PHP Memory Exhaustion Error

A typical log message may look like:

Allowed memory size exhausted

If you see this, increase the PHP memory limit appropriately.

For example:

memory_limit = 512M

After changing the relevant PHP configuration, reload/restart PHP-FPM as required.

Then retry the failing Magento operation.

Do not keep increasing memory indefinitely. If a simple request consumes excessive memory, investigate the extension, theme, query, or code responsible.

---

Step 27: Check for a “Class Not Found” Error

If logs contain something like:

Class "Vendor\Module\Something" not found

possible causes include:

• Missing Composer package
• Disabled module
• Missing generated class
• Incomplete deployment
• Incorrect autoload files

Try:

composer dump-autoload

Then:

rm -rf generated/code/*
rm -rf generated/metadata/*
php bin/magento setup:di:compile

If the class belongs to a third-party extension, verify that the extension is installed correctly and compatible with the current Magento and PHP versions.

---

Step 28: Check for a “Permission Denied” Error

If the log contains:

Permission denied

identify the affected file or directory.

Check:

ls -lah /path/to/file

and:

namei -l /path/to/file

Correct ownership and permissions according to your hosting environment.

Avoid using broad permission changes such as:

chmod -R 777

because they can create security vulnerabilities.

---

Step 29: Test Magento in a Controlled Environment

If the error is difficult to reproduce, use a staging environment.

Clone the affected Magento installation and database, then reproduce the problem there.

This allows you to test:

• Extension changes
• PHP configuration
• Magento compilation
• Composer changes
• Theme modifications
• Cache settings

without risking the live store.

---

Step 30: Restore From a Known-Good Backup

If troubleshooting has not solved the problem and you have a verified backup, restoration may be the safest option.

A complete recovery may require restoring:

Magento application files
Database
Media files
env.php
Custom modules
Custom themes
Composer configuration

After restoring, verify:

php bin/magento --version
php bin/magento cache:flush
php bin/magento indexer:reindex

Then test:

• Homepage
• Product pages
• Customer login
• Cart
• Checkout
• Admin
• Payment gateway

Do not restore only the files when the problem involves database changes, such as a failed Magento upgrade.

---

Magento 500 Error Troubleshooting by Symptom

Symptom	Likely Cause
500 immediately after PHP upgrade	PHP compatibility
500 after installing extension	Extension conflict
500 after Composer operation	Dependency problem
500 after migration	PHP, permissions, env.php, or server configuration
500 after editing .htaccess	Apache configuration
Admin works, storefront fails	Theme or frontend extension
Storefront works, Admin fails	Admin configuration, extension, or authentication issue
CSS/JS missing with errors	Static-content or permissions issue
Database error in logs	Database credentials/service
“Class not found”	Composer/module/generated-code issue
“Allowed memory size exhausted”	PHP memory limit
“Permission denied”	Ownership/permissions
Search-related failures	OpenSearch/Elasticsearch
Random failures under load	Resource or PHP-FPM limits

---

Useful Magento Commands for 500 Errors

Check Magento version:

php bin/magento --version

Check deployment mode:

php bin/magento deploy:mode:show

Check maintenance mode:

php bin/magento maintenance:status

Check cache:

php bin/magento cache:status

Flush cache:

php bin/magento cache:flush

Check modules:

php bin/magento module:status

Check indexers:

php bin/magento indexer:status

Reindex:

php bin/magento indexer:reindex

Compile Magento:

php bin/magento setup:di:compile

Deploy static files:

php bin/magento setup:static-content:deploy -f

Run cron:

php bin/magento cron:run

Validate env.php:

php -l app/etc/env.php

Validate Composer:

composer validate

Regenerate Composer autoload files:

composer dump-autoload

---

What Not to Do When Fixing a Magento 500 Error

Do Not Immediately Reinstall Magento

Your database and application may be perfectly recoverable.

Do Not Delete the Database

A 500 error does not mean that the database is corrupted.

Do Not Run composer update Without a Plan

Changing dependency versions can introduce more problems.

Do Not Use chmod 777

Correct ownership and permissions instead.

Do Not Delete Core Magento Directories

Randomly deleting vendor, app, or other core directories can make recovery significantly harder.

Do Not Modify the Database Without a Backup

Direct SQL changes should be carefully planned and tested.

Do Not Hide the Problem

Avoid permanently displaying detailed PHP errors on a production website. Use logs and a controlled development/staging environment for debugging.

---

Prevention: How to Avoid Future Magento 500 Errors

A good maintenance strategy can prevent many Magento failures.

Maintain Regular Backups

Back up both files and databases and periodically test that the backups can actually be restored.

Use Staging

Test Magento, PHP, extension, and theme changes before applying them to production.

Keep a Record of Changes

Document:

• Magento version
• PHP version
• Composer version
• Extensions
• Theme
• Redis
• Search engine
• Database version
• Server configuration

Monitor Server Resources

Watch:

• CPU
• RAM
• Disk space
• Inodes
• PHP-FPM
• Database performance

Update Carefully

Do not combine several major changes at once unless necessary. Separating Magento, PHP, extension, and server upgrades makes troubleshooting much easier.

---

Magento 500 Error Recovery Checklist

Use this checklist when your Magento store returns a 500 error:

• Create a backup
• Identify what changed before the error
• Check Magento logs
• Check web-server logs
• Check PHP version
• Check PHP-FPM
• Check required PHP extensions
• Check PHP memory limit
• Check disk space
• Check file ownership
• Check permissions
• Validate app/etc/env.php
• Test database connectivity
• Check Composer dependencies
• Check recently installed extensions
• Check custom theme changes
• Clear Magento cache
• Regenerate generated code if required
• Deploy static content if required
• Check Redis
• Check OpenSearch/Elasticsearch
• Check indexers
• Check cron
• Check maintenance mode
• Test storefront
• Test Admin Panel
• Test checkout
• Restore from a verified backup if necessary

Conclusion

A Magento 500 Internal Server Error is a symptom rather than a specific problem. The most effective way to fix it is to work from the infrastructure upward: logs, PHP, PHP-FPM, permissions, Magento configuration, Composer dependencies, extensions, cache, database, search services, and web-server configuration.

Start by identifying the first meaningful error in the logs rather than making multiple changes at once. This makes it much easier to determine whether the problem comes from Magento itself, a third-party extension, the PHP environment, or the underlying server.

For production stores, always keep a tested backup and staging environment available. These two safeguards can turn a potentially serious Magento failure into a straightforward recovery.