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

Invalid module definition for module '{moduleName}': The mod

Error message

Invalid module definition for module '{moduleName}': The module definition must be an array or an object

What it means

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.

Source

Thrown at phalcon/Cli/Console.zep:101

        }

        if moduleName {
            if this->eventsManager !== null {
                if this->eventsManager->fire("console:beforeStartModule", this, moduleName) === false {
                    return false;
                }
            }

            /**
             * Gets the module definition
             */
            let module = this->getModule(moduleName);

            /**
             * A module definition must be an array or an object
             */
            if unlikely (typeof module !== "array" && typeof module !== "object") {
                throw new InvalidModuleDefinition(
                    moduleName,
                    "The module definition must be an array or an object"
                );
            }

            /**
             * 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";
                }

                /**

View on GitHub (pinned to b7419de9cd)

Solutions

1. Change the definition to an array: ['className' => 'App\Admin\Module', 'path' => __DIR__ . '/modules/admin/Module.php']
2. Or use a Closure: 'admin' => function ($di) { return new \App\Admin\Module($di); }
3. If the modules array comes from config, dump it (var_export($console->getModules())) before handle() and fix any scalar entries

Example fix

// before
$console->registerModules([
    'admin' => 'App\Admin\Module',
]);
$console->handle();

// after
$console->registerModules([
    'admin' => [
        'className' => 'App\Admin\Module',
        'path'      => __DIR__ . '/modules/admin/Module.php',
    ],
]);
$console->handle();

$modules = [
    'admin' => ['className' => 'App\Admin\Module', 'path' => __DIR__ . '/modules/admin/Module.php'],
];
foreach ($modules as $name => $definition) {
    if (!is_array($definition) && !$definition instanceof \Closure) {
        throw new InvalidArgumentException(sprintf(
            'Module "%s" must be an array or a Closure, got %s',
            $name,
            gettype($definition)
        ));
    }
}
$console->registerModules($modules);

/**
 * A Phalcon CLI module definition must be an array (className/path keys)
 * or a Closure that receives the DI container.
 */
function isValidCliModuleDefinition($definition): bool
{
    return is_array($definition) || $definition instanceof \Closure;
}

try {
    $console->handle();
} catch (\Phalcon\Cli\Console\Exception\InvalidModuleDefinition $e) {
    // $e->getMessage() names the module and which rule failed (array/object vs Closure)
    $stderr->writeln('Fix module definition: ' . $e->getMessage());
    exit(1);
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Invalid module definition for module '{moduleName}': The mod
• Module definition path '{path}' does not exist
• A dependency injection container is required to access inter
• Arguments must be an array or string, {type} given
• 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/16c40411875485bd. Report an issue: GitHub.