Magento Module Admin Controller Returns 404 Error

Magento Module Admin Controller Returns 404 Error

August 28, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Magento Module Admin Controller Returns 404 Error

Resolving Magento Module Admin Controller 404 Error: A Comprehensive Guide

As a senior developer working extensively on e-commerce platforms, I often encounter developers facing the dreaded “404 error” when attempting to access custom admin controllers in Magento. In this blog post, we will dive deep into the issue you’re experiencing and provide a step-by-step guide to resolve it.

Understanding the 404 Error in Magento Admin Controllers

When you receive a 404 error while trying to access a custom admin controller in Magento, it typically means that the system cannot locate the requested resource. This usually happens due to incorrect module configuration or routing issues.

In your case, you are following a tutorial to create a simple reports module (kudos for learning by doing!), but when you try to open http://localhost/dev/admin/adminhtml/report_example/simple, Magento throws a 404 error.

Analyzing the Module Configuration

Let’s break down your module configuration and identify potential issues:

app/etc/modules/Package_Custom.xml

This file is properly configured with an active status and local code pool. The syntax looks correct, so this shouldn’t be the cause of the 404 error.

<?xml version="1.0"?>
<config>
    <modules>
        <Package_Custom>
            <active>true</active>
            <codePool>local</codePool>
        </Package_Custom>
    </modules>
</config>

app/code/local/Package/Custom/etc/adminhtml.xml

The adminhtml.xml file is responsible for defining the menu configuration. You have correctly defined a new tab (“Custom”) and a child node (“Simple Report”) with an action pointing to your controller.

<?xml version="1.0"?>
<config>
    <menu>
        <custom translate="title" module="custom">
            <title>Custom</title>
            <sort_order>15</sort_order>
            <children>
                <simple translate="title" module="custom">
                    <title>Simple Report</title>
                    <sort_order>1</sort_order>
                    <action>adminhtml/report_example/simple</action>
                </simple>
            </children>
        </custom>
    </menu>
</config>

app/code/local/Package/Custom/etc/config.xml

The config.xml file is where you define your module’s version and admin router settings. Your configuration appears to be correct, with the before attribute set to “Mage_Adminhtml” for the custom module.

<?xml version="1.0"?>
<config>
    <modules>
        <Package_Custom>
            <version>1.0.0</version>
        </Package_Custom>
    </modules>
    <admin>
        <routers>
            <adminhtml>
                <args>
                    <modules>
                        <custom before="Mage_Adminhtml">Package_Custom_Adminhtml</custom>
                    </modules>
                </args>
            </adminhtml>
        </routers>
    </admin>
</config>

Identifying the Issue: Controller Naming Convention

The 404 error you’re encountering is likely due to an incorrect naming convention for your controller. Magento uses a specific naming pattern for admin controllers, and you seem to be missing the “Controller” suffix in your filename.

Incorrect File Name (Causes 404 Error)

app/code/local/Package/Custom/controllers/Adminhtml/Report/ExampleController.php

Correct File Name

The correct filename should have the “Controller” suffix, like this:

app/code/local/Package/Custom/controllers/Adminhtml/Report/ExampleController.php

Renaming your controller to follow the correct naming convention should resolve the 404 error. Make sure all your admin controllers adhere to this pattern.

Additional Best Practices for Magento Module Development

While you’re already on the right track, here are a few best practices to keep in mind when developing custom modules:

  1. Use Composer: For better dependency management and autoloading capabilities.
  2. Follow Magento Coding Standards: This ensures your code integrates seamlessly with the core system.
  3. Test Your Modules: Writing unit tests and integration tests can save you from headaches down the line.

Conclusion

In summary, the 404 error you encountered was likely due to an incorrect naming convention for your admin controller in Magento. By ensuring that your controller filename adheres to the “Controller” suffix pattern (e.g., ExampleController.php instead of ExampleController.php), you should be able to resolve the issue.

Remember, patience and attention to detail are key when working with Magento’s complex architecture. If you continue facing any challenges or have further questions about Magento module development, feel free to explore our Magento Tutorials for more in-depth guidance.

Happy coding!

Extensions Admin Configuration Pricing

Our network