phalcon/cphalcon · error · Phalcon\Autoload\Exceptions\LoaderDirectoriesNotArray

The directories parameter is not a string or array for the '

Error message

The directories parameter is not a string or array for the '{name}' namespace

What it means

Loader::checkDirectories() normalizes the directories argument for registerNamespaces()/registerClasses()/registerDirs()-style registration (the 'name' in the message is the namespace/class key when applicable). Each directories value must be a string or an array of strings; anything else (null, int, object, bool) throws LoaderDirectoriesNotArray with the offending namespace name in the message.

Source

Thrown at phalcon/Autoload/Loader.zep:658

     * Checks if the directories is an array or a string and throws an exception
     * if not. It converts the string to an array and then traverses the array
     * to normalize the directories with the proper directory separator at the
     * end
     *
     * @param mixed $directories
     *
     * @return autoload_strings
     */
    private function checkDirectories(
        directories,
        string dirSeparator,
        string name = ""
    ) -> array {
        var directory;
        array results;

        if (!is_string(directories) && !is_array(directories)) {
            throw new LoaderDirectoriesNotArray(name);
        }

        if (is_string(directories)) {
            let directories = [directories];
        }

        let results = [];
        for directory in directories {
            let directory = rtrim(directory, dirSeparator) . dirSeparator;

            let results[directory] = directory;
        }

        return results;
    }

    private function registerAutoload(bool prepend) -> bool
    {

View on GitHub (pinned to b7419de9cd)

Solutions

1. Give the namespace a real path string or array of strings: $loader->registerNamespaces(['App' => app_path()])
2. Sanitize config-derived values: array_filter($paths) to drop nulls before registering
3. Guard env-derived roots: $paths['App'] = $envRoot ?? __DIR__ . '/src'

Example fix

// before
$loader->registerNamespaces(['App' => getenv('APP_PATH')]); // false/null when unset

// after
$loader->registerNamespaces(['App' => getenv('APP_PATH') ?: __DIR__ . '/../src']);

foreach ($namespaces as $ns => $dirs) {
    if (!is_string($dirs) && !is_array($dirs)) {
        unset($namespaces[$ns]); // or throw with the namespace name
    }
}
$loader->registerNamespaces($namespaces);

function isValidDirectorySpec($dirs): bool
{
    return is_string($dirs) || is_array($dirs);
}

When it happens

Trigger: $loader->registerNamespaces(['App' => null]); $loader->registerNamespaces(['App' => 123]); passing an object or boolean as the directory spec for a namespace; registerDirs() fed a non-array/non-string value.

Common situations: Env-driven paths that resolve to null when an env var is missing; config merges that null out namespace paths; YAML parsing an unquoted numeric path as int; refactoring that leaves a namespace key without its directories.

Related errors

• The 'method' parameter must be either a callable or NULL
• Malformed ACL snapshot structure
• Path '{path}' is not a valid target path
• Asset '{path}' does not have a valid target path
• Stream adapter file does not exist: {path}

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