phalcon/cphalcon · error · Phalcon\Auth\Exceptions\OptionRequiresArray

Auth {context} requires '{key}' to be a non-empty array

Error message

Auth {context} requires '{key}' to be a non-empty array

What it means

Options::requireArray() is the Auth component's validator for array-valued config entries. It fetches the key from the options array and throws OptionRequiresArray (message includes the context, e.g. "guard 'web'") when the key is missing, its value is not an array, or the array is empty (empty() also rejects [] and arrays of only null/false). A typical use is ManagerFactory::load() requiring every guard config to have a non-empty 'adapter' array.

Source

Thrown at phalcon/Auth/Internal/Options.zep:59

        /** @var list<array{id?: int|string}&array<string, mixed>> */
        return array_values(value);
    }

    /**
     * @phpstan-param array<string, mixed> $options
     *
     * @phpstan-return array<string, mixed>
     * @throws Exception
     */
    public static function requireArray(array options, string key, string context) -> array
    {
        var value;

        fetch value, options[key];

        if (typeof value !== "array" || empty(value)) {
            throw new OptionRequiresArray(context, key);
        }

        return value;
    }

    /**
     * @phpstan-param array<string, mixed> $options
     *
     * @throws Exception
     */
    public static function requireString(array options, string key, string context) -> string
    {
        var value;

        fetch value, options[key];

        if (typeof value !== "string" || value === "") {
            throw new OptionRequiresString(context, key);

View on GitHub (pinned to b7419de9cd)

Solutions

1. Add the missing non-empty array under the key named in the message - most commonly: guards: {web: {adapter: {name: 'stream', options: {...}}, type: 'session'}}
2. If the value was a scalar/null, convert it to the array shape the component documents
3. Validate your auth config at boot (schema/assertion) so mistakes surface with your own error before the factory runs

Example fix

// before
'guards' => [
    'web' => ['type' => 'session'],
],

// after
'guards' => [
    'web' => [
        'adapter' => ['name' => 'stream', 'options' => ['file' => 'storage/users.json']],
        'type' => 'session',
    ],
],

foreach ($config['guards'] ?? [] as $name => $guard) {
    if (!isset($guard['adapter']) || !is_array($guard['adapter']) || $guard['adapter'] === []) {
        throw new InvalidArgumentException("guard '{$name}' needs a non-empty 'adapter' array");
    }
}

function hasNonEmptyArrayOption(array $options, string $key): bool
{
    return isset($options[$key]) && is_array($options[$key]) && $options[$key] !== [];
}

When it happens

Trigger: Auth config where a guard entry lacks its 'adapter' block: guards: {web: {type: 'session'}}; guards.web.adapter set to a string or null instead of an array; guards.web.adapter: [] left empty.

Common situations: Hand-written auth config arrays missing nested sections; YAML/PHP config merge that silently drops the adapter block; environment-specific config overriding adapter with a scalar; refactoring that emptied the array during a rename.

Related errors

• Auth {context} requires '{key}' to be a non-empty string
• Malformed ACL snapshot structure
• Stream adapter file does not exist: {path}
• Stream adapter file is not valid JSON: {path}
• Stream adapter file does not contain a JSON array: {path}

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