phalcon/cphalcon · error · Phalcon\Cli\Console\Exceptions\ModuleDefinitionPathNotFound

Module definition path '{path}' does not exist

Error message

Module definition path '{path}' does not exist

What it means

A CLI module defined as an array may carry a 'path' key pointing to the PHP file that defines the module class. Before require_once, Phalcon checks the path with phpFileExists; if the file is not there, ModuleDefinitionPathNotFound is thrown with the exact path that failed.

Source

Thrown at phalcon/Cli/Console.zep:124

            /**
             * An array module definition contains a path to a module
             * definition class
             */
            if typeof module === "array" {
                /**
                 * Class name used to load the module definition
                 */
                if !fetch className, module["className"] {
                    let className = "Module";
                }

                /**
                 * If developer specify a path try to include the file
                 */
                if fetch path, module["path"] {
                    if unlikely !this->phpFileExists(path) {
                        throw new ModuleDefinitionPathNotFound(path);
                    }

                    if !class_exists(className, false) {
                        require_once path;
                    }
                }

                let moduleObject = <ModuleDefinitionInterface> this->container->get(className);

                /**
                 * 'registerAutoloaders' and 'registerServices' are
                 * automatically called
                 */
                moduleObject->registerAutoloaders(this->container);
                moduleObject->registerServices(this->container);
            } else {
                /**
                 * A module definition object, can be a Closure instance

View on GitHub (pinned to b7419de9cd)

Solutions

1. Use absolute paths built from __DIR__, e.g. dirname(__DIR__) . '/modules/api/Module.php'
2. Validate at boot that every module's 'path' passes is_file()
3. Check the deploy artifact actually contains the module directories

Example fix

// before
'path' => 'app/modules/api/Module.php',

// after
'path' => dirname(__DIR__) . '/app/modules/api/Module.php',

foreach ($modules as $name => $definition) {
    if (is_array($definition) && isset($definition['path'])) {
        if (!is_file($definition['path'])) {
            throw new RuntimeException(sprintf(
                'Module "%s" path does not exist: %s',
                $name,
                $definition['path']
            ));
        }
    }
}
$console->registerModules($modules)->handle();

try {
    $console->handle();
} catch (\Phalcon\Cli\Console\Exception\ModuleDefinitionPathNotFound $e) {
    // Message contains the exact missing path; log it and fail fast
    $stderr->writeln('Missing module file: ' . $e->getMessage());
    exit(1);
}

When it happens

Trigger: registerModules(['api' => ['className' => 'App\Api\Module', 'path' => 'app/modules/api/Module.php']]) where the file is missing, or the relative path is resolved from a working directory other than the one the CLI script was started from.

Common situations: CLI scripts launched from a different cwd (cron job, systemd unit, global bin) so relative paths break; deploying without the module directory; case-sensitivity mismatch between dev machines (macOS/Windows) and Linux servers.

Related errors

• Invalid module definition for module '{moduleName}': The mod
• Invalid module definition for module '{moduleName}': The mod
• Arguments must be an array or string, {type} given
• Before-Match callback is not callable in matched route '{pat
• Before-Match callback is not callable in matched route '{pat

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