{"record":{"id":"4ff5d49c6e7edfcc","repo":"phalcon/cphalcon","slug":"the-session-adapter-is-not-valid","errorCode":null,"errorMessage":"The session adapter is not valid","messagePattern":"The session adapter is not valid","errorType":"exception","errorClass":"Phalcon\\Session\\Exceptions\\InvalidSessionAdapter","httpStatus":null,"severity":"error","filePath":"phalcon/Session/Manager.zep","lineNumber":365,"sourceCode":"            return false;\n        }\n\n        /**\n         * Verify that the session cookie value uses the PHP session ID\n         * alphabet ([a-zA-Z0-9,-], depending on session.sid_bits_per_character),\n         * otherwise we unset the cookie to allow it to be created by\n         * session_start().\n         */\n        let name = this->getName();\n\n        if fetch value, _COOKIE[name] {\n            if !preg_match(\"/^[a-zA-Z0-9,-]+$/D\", value) {\n                unset _COOKIE[name];\n            }\n        }\n\n        if unlikely !(this->adapter instanceof SessionHandlerInterface) {\n            throw new InvalidSessionAdapter();\n        }\n\n        /**\n         * Register the adapter\n         */\n        session_set_save_handler(this->adapter);\n\n        /**\n         * Start the session\n         */\n        return session_start();\n    }\n\n    /**\n     * Returns the status of the current session.\n     */\n    public function status() -> int\n    {","sourceCodeStart":347,"sourceCodeEnd":383,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Session/Manager.zep#L347-L383","documentation":"Manager::start() registers the handler with session_set_save_handler() before calling session_start(); it requires that an adapter implementing SessionHandlerInterface was set via setAdapter(). If no adapter was registered, or the object is not a session handler (e.g. a Phalcon Storage cache adapter), start() throws InvalidSessionAdapter.","triggerScenarios":"Calling $session->start() on a Manager built with new Manager() and never calling setAdapter(); a DI 'session' service that returns the Manager without wiring the adapter; passing a Phalcon\\Storage\\Adapter\\* object, which is a cache adapter, not a session handler.","commonSituations":"DI misconfiguration where the adapter line was dropped during refactor; code migrated from raw session_start(); developers confusing Storage adapters (cache) with Session adapters because both are named 'adapter'.","solutions":["Register a real session handler before start(): $session->setAdapter(new \\Phalcon\\Session\\Adapter\\Stream(['savePath' => ...])) or the Redis adapter","When using the DI container, create the adapter inside the 'session' service closure so it can never be missing","For custom handlers, implement \\SessionHandlerInterface (open, close, read, write, destroy, gc, optionally validateId, updateTimestamp)","Fail fast after wiring: if (!$session->getAdapter() instanceof \\SessionHandlerInterface) { throw new ...; }"],"exampleFix":"// before\n$session = new \\Phalcon\\Session\\Manager();\n$session->start(); // InvalidSessionAdapter\n\n// after\n$session = new \\Phalcon\\Session\\Manager();\n$session->setAdapter(new \\Phalcon\\Session\\Adapter\\Stream(['savePath' => '/tmp']));\n$session->start();","handlingStrategy":"validation","validationCode":"if (!$session->getAdapter() instanceof \\SessionHandlerInterface) {\n    $session->setAdapter(\n        new \\Phalcon\\Session\\Adapter\\Stream(['savePath' => $config->path('session.savePath')])\n    );\n}","typeGuard":"function isSessionHandler(mixed $adapter): bool\n{\n    return $adapter instanceof \\SessionHandlerInterface;\n}","tryCatchPattern":"try {\n    $session->start();\n} catch (\\Phalcon\\Session\\Exceptions\\InvalidSessionAdapter $e) {\n    $logger->critical('Session manager has no adapter; check DI service wiring');\n    throw $e;\n}","preventionTips":["Construct Manager and adapter together in one factory/DI closure","Never reuse a Phalcon\\Storage cache adapter as a session handler","Add a startup assertion on getAdapter() instanceof SessionHandlerInterface in test suites"],"tags":["php","phalcon","session","configuration","dependency-injection"],"backgroundTag":"missing-session-adapter","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}