{"record":{"id":"4fb7b95b60983691","repo":"phalcon/cphalcon","slug":"module-definition-path-path-does-not-exist","errorCode":null,"errorMessage":"Module definition path '{path}' does not exist","messagePattern":"Module definition path '(.+?)' does not exist","errorType":"exception","errorClass":"Phalcon\\Cli\\Console\\Exceptions\\ModuleDefinitionPathNotFound","httpStatus":null,"severity":"error","filePath":"phalcon/Cli/Console.zep","lineNumber":124,"sourceCode":"\n            /**\n             * An array module definition contains a path to a module\n             * definition class\n             */\n            if typeof module === \"array\" {\n                /**\n                 * Class name used to load the module definition\n                 */\n                if !fetch className, module[\"className\"] {\n                    let className = \"Module\";\n                }\n\n                /**\n                 * If developer specify a path try to include the file\n                 */\n                if fetch path, module[\"path\"] {\n                    if unlikely !this->phpFileExists(path) {\n                        throw new ModuleDefinitionPathNotFound(path);\n                    }\n\n                    if !class_exists(className, false) {\n                        require_once path;\n                    }\n                }\n\n                let moduleObject = <ModuleDefinitionInterface> this->container->get(className);\n\n                /**\n                 * 'registerAutoloaders' and 'registerServices' are\n                 * automatically called\n                 */\n                moduleObject->registerAutoloaders(this->container);\n                moduleObject->registerServices(this->container);\n            } else {\n                /**\n                 * A module definition object, can be a Closure instance","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Cli/Console.zep#L106-L142","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use absolute paths built from __DIR__, e.g. dirname(__DIR__) . '/modules/api/Module.php'","Validate at boot that every module's 'path' passes is_file()","Check the deploy artifact actually contains the module directories"],"exampleFix":"// before\n'path' => 'app/modules/api/Module.php',\n\n// after\n'path' => dirname(__DIR__) . '/app/modules/api/Module.php',","handlingStrategy":"validation","validationCode":"foreach ($modules as $name => $definition) {\n    if (is_array($definition) && isset($definition['path'])) {\n        if (!is_file($definition['path'])) {\n            throw new RuntimeException(sprintf(\n                'Module \"%s\" path does not exist: %s',\n                $name,\n                $definition['path']\n            ));\n        }\n    }\n}\n$console->registerModules($modules)->handle();","typeGuard":null,"tryCatchPattern":"try {\n    $console->handle();\n} catch (\\Phalcon\\Cli\\Console\\Exception\\ModuleDefinitionPathNotFound $e) {\n    // Message contains the exact missing path; log it and fail fast\n    $stderr->writeln('Missing module file: ' . $e->getMessage());\n    exit(1);\n}","preventionTips":["Build module paths with __DIR__/dirname(__DIR__) so they never depend on the current working directory","Add a boot check that is_file() passes for every module 'path' before handle()","In deploys, verify the module directory tree is present (e.g. a smoke test that runs the console once)"],"tags":["phalcon","cli","module","file-path","deployment"],"backgroundTag":"file-not-found","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}