phalcon/cphalcon · error · Phalcon\Application\Exceptions\ModuleNotRegistered

Module '{name}' is not registered in the application

Error message

Module '{name}' is not registered in the application

What it means

Phalcon\Application\AbstractApplication::getModule(name) looks up the module definition in the modules array populated by registerModules()/setModules(). If the key is absent it throws ModuleNotRegistered — the application has no definition (className/path/closure) for that module name.

Source

Thrown at phalcon/Application/AbstractApplication.zep:69

     */
    public function getDefaultModule() -> string
    {
        return this->defaultModule;
    }

    /**
     * Gets the module definition registered in the application via module name
     *
     * @param string name
     *
     * @phpstan-return Closure|application_module_definition
     */
    public function getModule(string name) -> mixed
    {
        var module;

        if unlikely !fetch module, this->modules[name] {
            throw new ModuleNotRegistered(name);
        }

        return module;
    }

    /**
     * Return the modules registered in the application
     *
     * @phpstan-return application_modules
     */
    public function getModules() -> array
    {
        return this->modules;
    }

    /**
     * Register an array of modules present in the application
     *

View on GitHub (pinned to b7419de9cd)

Solutions

1. Register the module: `$application->registerModules(['admin' => ['className' => Admin\Module::class, 'path' => ...]])`
2. Verify the exact key: `var_dump(array_keys($application->getModules()))` and compare case
3. Ensure registration happens before anything (router, dispatcher forward, your own code) calls getModule()

Example fix

// before
$module = $application->getModule('admin'); // ModuleNotRegistered
// after
$application->registerModules([
    'admin' => ['className' => \App\Admin\Module::class],
]);
$module = $application->getModule('admin');

$modules = $application->getModules();
if (!isset($modules[$name])) {
    throw new InvalidArgumentException('Unknown module: ' . $name . '. Registered: ' . implode(', ', array_keys($modules)));
}
$module = $application->getModule($name);

try {
    $module = $application->getModule($name);
} catch (\Phalcon\Application\Exceptions\ModuleNotRegistered $e) {
    $response->setStatusCode(404)->setContent('Module not found')->send();
}

When it happens

Trigger: `$application->getModule('frontend')` before registerModules(), with a typo, or with wrong case (module keys are case-sensitive); a router/dispatcher forwarding to a module name that was never registered.

Common situations: Multi-module apps where the router returns a module name not present in the modules config; registering modules conditionally per environment and forgetting one; renaming a module directory without updating the modules array.

Related errors

• Collection does not have an annotation called '{name}'
• The collection '{name}' does not exist in the manager
• Invalid route position
• The not-found paths must be an array or string

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/bc91846d3fd799cc. Report an issue: GitHub.