The Errors Everyone Meets

Blank white page, 404 on a new route, a module that will not enable, a template change with no effect, and the usual cause of each.

Syntaxbin/magento module:status Vendor_Module

Blank white page

Almost always a fatal error or an exception with error display off. Check var/log/exception.log and the newest file in var/report/ first. Then run bin/magento deploy:mode:show: in production mode a blank page is expected behaviour for an error, not a separate bug.

404 on a new route

A route has two names. frontName is the first segment of the URL; id is the internal name used elsewhere, including layout handles. Swapping them produces a 404 with no log entry. The rest of the URL maps to directories: /pricing/feed/status looks for Controller/Feed/Status.php with an execute() method. Routes are cached, so run bin/magento cache:flush.

A module that will not enable

bin/magento module:status Vendor_Module tells you whether Magento has even found it. If it is missing entirely, the usual cause is a mismatch between the name in registration.php and the name in etc/module.xml. After module:enable, run bin/magento setup:upgrade; the enable alone only edits app/etc/config.php.

A template change with no effect

Rendered HTML is cached. Clear block_html and full_page. If the site is in production mode, the template may also be served from a minified copy under var/view_preprocessed. Turn on template hints to see which file is actually rendering.

Example

Example · xml
<!-- app/code/Vendor/Pricing/etc/frontend/routes.xml -->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/routes.xsd">
    <router id="standard">
        <!-- frontName is the URL segment. id is the internal name. -->
        <route id="vendor_pricing" frontName="pricing">
            <module name="Vendor_Pricing"/>
        </route>
    </router>
</config>

When to use it

  • A new controller returns 404 and nothing is written to any log.
  • A deploy leaves the storefront blank and you have minutes to find out why.
  • A module copied from another project does not appear in module:status.
  • A .phtml edit is live on disk but the page keeps rendering the old markup.

More examples

Triage a blank page

The order matters. An uncaught exception in production mode writes a report under var/report and logs a CRITICAL record whose context carries the report_id; because that context has no 'exception' key the record goes to system.log rather than exception.log, and the browser shows the error page with the id. A true PHP fatal error, such as a class that cannot be autoloaded after a half-finished deploy, happens before Magento's handlers exist: nothing appears in var/log and the browser shows nothing at all. If both Magento files are silent, the answer is in the PHP-FPM or web server error log, and it is usually a missing generated class or a permissions problem on var/ or generated/.

Example · bash
bin/magento deploy:mode:show
# Current application mode: production.

# 1. The most recent report, which is what the blank page produced.
ls -t var/report | head -n 3
php -r 'print_r(json_decode(file_get_contents("var/report/" . trim(shell_exec("ls -t var/report | head -n 1"))), true));'

# 2. The exception log for the same moment.
tail -n 50 var/log/exception.log

# 3. A fatal error never reaches Magento's logger. Check PHP's own log.
php -i | grep '^error_log'
tail -n 50 /var/log/php-fpm/error.log

A module Magento cannot see

Module does not exist and Module is disabled are different problems. Does not exist means registration never happened: the name string in registration.php does not match the name attribute in etc/module.xml, or the directory is at the wrong depth under app/code, or the file permissions hide it from the PHP user. Disabled means Magento found it and app/etc/config.php has it set to 0, which module:enable fixes. In both cases setup:upgrade is what writes the module's schema and runs its data patches; enabling without it leaves tables missing.

Example · bash
bin/magento module:status Vendor_Pricing
# Module does not exist.

# Do the two declarations agree on the name?
grep -r 'Vendor_Pricing' app/code/Vendor/Pricing/registration.php \
    app/code/Vendor/Pricing/etc/module.xml

# Is it listed, and with what value?
grep -n 'Vendor_Pricing' app/etc/config.php

bin/magento module:enable Vendor_Pricing
bin/magento setup:upgrade
bin/magento cache:flush

bin/magento module:status Vendor_Pricing
# Module is enabled

Make a template change show up

Template hints wrap every block's output with the path of the .phtml that produced it, which settles the common case where the edit was made to a file that is not the one in use, usually because a theme further up the inheritance chain overrides it. The command writes a configuration value, so it needs a cache flush to take effect. Only clear var/view_preprocessed and redeploy static content on a production-mode site; in developer mode both are rebuilt on demand and the deploy is wasted time.

Example · bash
# Which file is actually rendering?
bin/magento dev:template-hints:enable
# Template hints enabled.
bin/magento cache:flush

# ... read the paths printed on the page, then turn them off again ...
bin/magento dev:template-hints:disable
bin/magento cache:flush

# Clear only the caches that hold rendered HTML.
bin/magento cache:clean block_html full_page

# Production mode only: templates may be served minified from here.
bin/magento deploy:mode:show
rm -rf var/view_preprocessed/*
bin/magento setup:static-content:deploy en_US

Related

m2 first routem2 module enablem2 dev modesm2 layout debugm2 logs

Discussion

  • Be the first to comment on this lesson.