Recent Posts


A Better Magento 404 Page


Frustrated by Magento? Then you’ll love Commerce Bug, the must have debugging extension for anyone using Magento. Whether you’re just starting out or you’re a seasoned pro, Commerce Bug will save you and your team hours everyday. Grab a copy and start working with Magento instead of against it.

Updated for Magento 2! No Frills Magento Layout is the only Magento front end book you'll ever need. Get your copy today!

This entry is part 33 of 43 in the series Miscellaneous Magento Articles. Earlier posts include Magento Front Controller, Reinstalling Magento Modules, Clearing the Magento Cache, Magento's Class Instantiation Abstraction and Autoload, Magento Development Environment, Logging Magento's Controller Dispatch, Magento Configuration Lint, Slides from Magento Developer's Paradise, Generated Magento Model Code, Magento Knowledge Base, Magento Connect Role Directories, Magento Base Directories, PHP Error Handling and Magento Developer Mode, Magento Compiler Mode, Magento: Standard OOP Still Applies, Magento: Debugging with Varien Object, Generating Google Sitemaps in Magento, IE9 fix for Magento, Magento's Many 404 Pages, Magento Quickies, Commerce Bug in Magento CE 1.6, Welcome to Magento: Pre-Innovate, Magento's Global Variable Design Patterns, Magento 2: Factory Pattern and Class Rewrites, Magento Block Lifecycle Methods, Goodnight and Goodluck, Magento Attribute Migration Generator, Fixing Magento Flat Collections with Chaos, Pulse Storm Launcher in Magento Connect, StackExchange and the Year of the Site Builder, Scaling Magento at Copious, and Incremental Migration Scripts in Magento. Later posts include Anatomy of the Magento PHP 5.4 Patch, Validating a Magento Connect Extension, Magento Cross Area Sessions, Review of Grokking Magento, Imagine 2014: Magento 1.9 Infinite Theme Fallback, Magento Ultimate Module Creator Review, Magento Imagine 2014: Parent/Child Themes, Early Magento Session Instantiation is Harmful, Using Squid for Local Hostnames on iPads, and Magento, Varnish, and Turpentine.

One of the most common Magento questions on Stack Overflow or the Magento Stack Exchange is a variation on “why does my MVC controller 404?” While powerful, Magento’s configuration based MVC system leaves lots of room for subtle configuration errors. Not only do you need to name your controller file correctly, you also need to have a multiple node XML configuration string in your module’s config.xml file. A multiple node configuration string that contains terms like router, frontName, and args — all of which mean something to programmers, but whose meanings are unclear in Magento.

As part of my unofficial December 2013 open-source extravaganza, I decided it was time to fix this problem with a better Magento 404 page, (download connect package).

Programmer’s 404 Pages

Most PHP frameworks have a programmatic 404 page. That is, when running in non-production mode, the framework will throw some sort of exception letting you know it couldn’t find a route to a controller action method for the specified URL. Take, for example, this Kohana 404 page.

Image of Kohana 404 Exception

While Magento has a default 404 page, Magento also has the burden of marketing itself directly to ecommerce business owners, and (the increasingly less-tech-savvy) agency owners. Because of these marketing requirements, the stock Magento 404 page is a standard end-user 404 page.

stock Magento 404 page

While most experienced Magento programmers will recognize this page as the no route 404 page, developers new to Magento don’t have that institutional knowledge. Additionally, there’s no hint on this page as to why the system produced a 404 error. That’s the problem my new Better 404 module solves.

Debugging a Route

The 404 page provided by the Better 404 module attempts to deduce why a particular URL has no MVC route. It does this in three steps

  1. Does a module claim the front name?

  2. If yes, is there a correctly named controller file for the module?

  3. If yes, is there a correctly named action method for the controller object?

While this next section assumes a familiarly with Magento’s controller dispatch, anyone with a passing familiarity with MVC routing should be able to follow along.

Front Names and config.xml

First, let’s consider the following URL

With the Better 404 module installed, this URL results in the following page

a 'no module claimed' better 404 page

The most import thing here is

No modules claim [no-such-page] as a <frontName/>.

When you see this error, it means there’s a problem in your config.xml file. Magento can’t find a module that “claims” the URL front name. The front name is the first portion of the URL string — in our example above that’s nosuchpage. The “front name” is a concept borrowed from the Zend Framework, where each PHP module “owns” a particular URL. This practice has fallen out of favor in more modern MVC systems, and even Magento has the ability to configure extra modules to check for controllers. Better 404 knows about these additional modules.

For example, if you attempt to access a nonexistent admin page.

You’ll see something like this.

image listing each module magento will check for an admin controller match

That is, the Better 404 module correctly reports the Mage_Adminhtml module has claimed the admin front name, but it also lets you know there’s a number of other modules Magento will look for controller matches in.

Which leads in nicely to our next section.

Incorrect Controller File

Consider the following URL

This URL results in a page that looks like this

A 'can't find the controller' better 404 page

Here the Better 404 page tells us which Magento module has claimed the catalog front name. (The catalog front name is part of the standard Magento distribution).

The Module/Front Name [catalog] is claimed by the Magento module Mage_Catalog.

However, it also lets us know it couldn’t find a controller file for the second part of the URL (nosuchpage)

The controller name no-such-page matches the following controller file, but this file does not exist.


When you see this error, it means your controller file is misnamed, or there’s a different module claiming this URL front name.

Incorrect Action Method

Finally, let’s consider the URL

This URL results in the following 404 page

Here we’ve fixed the previous problem by using the category controller in the Mage_Catalog model. However, we still have a problem

The action method nosuchpageAction is not present in the controller file.

When you see this error, it means you have a correctly configured module, with a correctly named controller file, but you’ve failed to add a correctly named publicly accessible action method.

Wrap Up

Controller routing is the first step is learning how to program in Magento, and initial frustrations setting up a basic hello world controller can drive new developers away from the platform. The Better 404 module aims to be one small step towards fixing that. Questions, comments, and feature suggestions are always welcome.

Originally published December 22, 2013
Series Navigation<< Incremental Migration Scripts in MagentoAnatomy of the Magento PHP 5.4 Patch >>

Copyright © Alana Storm 1975 – 2023 All Rights Reserved

Originally Posted: 22nd December 2013

email hidden; JavaScript is required