phalcon/cphalcon · error · TypeError

The parameter must be an instance of Collection or DiInterfa

Error message

The parameter must be an instance of Collection or DiInterface

What it means

The Auth component's ContainerResolver::ensureContainer() only accepts two container types: Phalcon\Contracts\Container\Service\Collection (the new Phalcon Container) or Phalcon\Di\DiInterface (the legacy DI). Anything else - an array, a string, null, or a foreign container (e.g. a PSR-11 implementation) - triggers a native TypeError. This guard runs at the top of every container-resolution helper in the Auth internals.

Source

Thrown at phalcon/Auth/Internal/ContainerResolver.zep:42

 * Intent is Container-first; the legacy Di is supported "with provisions":
 * definitions must be pre-registered (no autowiring), the one exception
 * being the fresh path, which lets Di build an unregistered but existing
 * class via its class builder.
 *
 * All legacy-Di failures are normalized to Phalcon\Container\Exceptions so
 * callers and userland catch a single exception family.
 */
final class ContainerResolver
{
    /**
     * Validates that the value is a supported container.
     *
     * @throws TypeError
     */
    public static function ensureContainer(var container) -> void
    {
        if (!(container instanceof Collection) && !(container instanceof DiInterface)) {
            throw new TypeError(
                "The parameter must be an instance of Collection or DiInterface"
            );
        }
    }

    /**
     * Resolves the first candidate service name that the container can
     * provide, as a shared instance. Used for framework services (request,
     * cookies, session) whose container key may vary between application
     * setups.
     *
     * @param list<string> $candidates
     *
     * @throws ContainerException
     */
    public static function requireService(var container, array candidates, string context) -> object
    {
        self::ensureContainer(container);

View on GitHub (pinned to b7419de9cd)

Solutions

1. Pass a Phalcon\Di\Di instance (typically the shared $di) or a Phalcon\Container\Container collection to the Auth factory/manager
2. Fetch the correct object explicitly: $di = Di::getDefault(); then hand $di to ManagerFactory
3. If you use a foreign container, bridge it by registering the needed services (session, cookies, request) into a Phalcon Di first

Example fix

// before
$factory = new ManagerFactory($hasher, $configArray);

// after
$di = \Phalcon\Di\Di::getDefault();
$factory = new ManagerFactory($hasher, $di);

if (!$container instanceof \Phalcon\Di\DiInterface
    && !$container instanceof \Phalcon\Contracts\Container\Service\Collection) {
    throw new TypeError('Expected Phalcon Di or Container collection');
}

function isPhalconContainer($container): bool
{
    return $container instanceof \Phalcon\Di\DiInterface
        || $container instanceof \Phalcon\Contracts\Container\Service\Collection;
}

When it happens

Trigger: Passing an invalid container anywhere the Auth component expects one: ManagerFactory constructor, ManagerFactory::load($config) with a wrong container object, or guard options where the container is supplied as an array config value; e.g. new ManagerFactory($hasher, ['di' => []]).

Common situations: Passing a PSR-11 container (League\Container, PHP-DI) assuming compatibility; passing the raw config array instead of the DI instance; passing null and expecting lazy setup; refactoring from Di to another container during a framework migration.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• Auth {context} requires service. None of the following are b
• Cannot resolve a fresh '{name}': it is not bound in the cont
• Cannot resolve a fresh '{name}': it is not registered in the
• Failed to resolve '{name}' from the Di container
• Malformed ACL snapshot structure

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