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

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

Error message

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

What it means

Options::requireString() validates string-valued config entries for the Auth component. It throws OptionRequiresString (message includes the failing context and key) when the key is missing from the options array, the value is not a string (int, array, null...), or it is the empty string ''. Common call sites are ManagerFactory requiring each guard's 'type', buildAdapter requiring the adapter 'name', and the Stream adapter requiring 'file'.

Source

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

            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);
        }

        return value;
    }

    /**
     * @param array<string, mixed> $options
     */
    public static function stringOrNull(array options, string key) -> string | null
    {
        var value;

        fetch value, options[key];

        return typeof value === "string" ? value : null;
    }
}

View on GitHub (pinned to b7419de9cd)

Solutions

1. Set the named key to a non-empty string - match the exact key in the message ('type', 'name', or 'file')
2. Cast or normalize values from env/YAML: (string) guards.web.type, and default empty strings to real values
3. Add a boot-time check that required config keys are non-empty strings before handing config to ManagerFactory::load()

Example fix

// before
'guards' => [
    'web' => [
        'adapter' => ['name' => '', 'options' => []],
        'type' => null,
    ],
],

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

foreach ($config['guards'] ?? [] as $name => $guard) {
    foreach (['type'] as $key) {
        $v = $guard[$key] ?? null;
        if (!is_string($v) || $v === '') {
            throw new InvalidArgumentException("guard '{$name}' needs a non-empty string '{$key}'");
        }
    }
}

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

When it happens

Trigger: Auth config entries like guards.web.type missing or set to null; guards.web.adapter.name: 123 (int) or '' (empty); a Stream adapter built with fromOptions() where the 'file' key is absent; adapter name defined with leading/trailing whitespace only.

Common situations: Env-driven config where an env var resolves to empty string in some environment; config merge that drops scalar keys; copy-paste of a guard block that kept the adapter name but lost 'type'; YAML parsing a numeric-looking name as int.

Related errors

• Auth {context} requires '{key}' to be a non-empty array
• 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/0a351f94967b7fc3. Report an issue: GitHub.