{"record":{"id":"16c40411875485bd","repo":"phalcon/cphalcon","slug":"invalid-module-definition-for-module-modulename","errorCode":null,"errorMessage":"Invalid module definition for module '{moduleName}': The module definition must be an array or an object","messagePattern":"Invalid module definition for module '(.+?)': The module definition must be an array or an object","errorType":"exception","errorClass":"Phalcon\\Cli\\Console\\Exceptions\\InvalidModuleDefinition","httpStatus":null,"severity":"error","filePath":"phalcon/Cli/Console.zep","lineNumber":101,"sourceCode":"        }\n\n        if moduleName {\n            if this->eventsManager !== null {\n                if this->eventsManager->fire(\"console:beforeStartModule\", this, moduleName) === false {\n                    return false;\n                }\n            }\n\n            /**\n             * Gets the module definition\n             */\n            let module = this->getModule(moduleName);\n\n            /**\n             * A module definition must be an array or an object\n             */\n            if unlikely (typeof module !== \"array\" && typeof module !== \"object\") {\n                throw new InvalidModuleDefinition(\n                    moduleName,\n                    \"The module definition must be an array or an object\"\n                );\n            }\n\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                /**","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Cli/Console.zep#L83-L119","documentation":"Thrown by Phalcon's CLI Console during handle() when a registered module's definition is neither an array nor an object. A module passed to registerModules() must be described either as an array (with keys like 'className' and 'path') or as an object that is specifically a Closure receiving the DI container. Any other type (a bare class-name string, int, bool, null) reaches the typeof check in Cli/Console.zep and fails immediately with the module name in the message.","triggerScenarios":"Calling $console->registerModules(['admin' => 'App\\Admin\\Module'])->handle() — the definition is a plain string, not an array or Closure. Same result for definitions that are null, integers, or booleans (e.g. a module list loaded from JSON/env that degraded to a scalar).","commonSituations":"Writing the class name directly instead of an array definition; assembling the modules array from config files or environment variables where a value collapses to a string; porting a web Console bootstrap into a CLI app and leaving a partially rewritten modules array.","solutions":["Change the definition to an array: ['className' => 'App\\Admin\\Module', 'path' => __DIR__ . '/modules/admin/Module.php']","Or use a Closure: 'admin' => function ($di) { return new \\App\\Admin\\Module($di); }","If the modules array comes from config, dump it (var_export($console->getModules())) before handle() and fix any scalar entries"],"exampleFix":"// before\n$console->registerModules([\n    'admin' => 'App\\Admin\\Module',\n]);\n$console->handle();\n\n// after\n$console->registerModules([\n    'admin' => [\n        'className' => 'App\\Admin\\Module',\n        'path'      => __DIR__ . '/modules/admin/Module.php',\n    ],\n]);\n$console->handle();","handlingStrategy":"validation","validationCode":"$modules = [\n    'admin' => ['className' => 'App\\Admin\\Module', 'path' => __DIR__ . '/modules/admin/Module.php'],\n];\nforeach ($modules as $name => $definition) {\n    if (!is_array($definition) && !$definition instanceof \\Closure) {\n        throw new InvalidArgumentException(sprintf(\n            'Module \"%s\" must be an array or a Closure, got %s',\n            $name,\n            gettype($definition)\n        ));\n    }\n}\n$console->registerModules($modules);","typeGuard":"/**\n * A Phalcon CLI module definition must be an array (className/path keys)\n * or a Closure that receives the DI container.\n */\nfunction isValidCliModuleDefinition($definition): bool\n{\n    return is_array($definition) || $definition instanceof \\Closure;\n}","tryCatchPattern":"try {\n    $console->handle();\n} catch (\\Phalcon\\Cli\\Console\\Exception\\InvalidModuleDefinition $e) {\n    // $e->getMessage() names the module and which rule failed (array/object vs Closure)\n    $stderr->writeln('Fix module definition: ' . $e->getMessage());\n    exit(1);\n}","preventionTips":["Always define CLI modules as an array with className/path or as a Closure","When the modules array is loaded from config files or env, validate each entry with is_array()/instanceof Closure before handle()","Keep a bootstrap test that constructs the console and registers modules in CI so definition regressions fail early"],"tags":["phalcon","cli","module","configuration","bootstrap"],"backgroundTag":"invalid-module-definition","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}