{"record":{"id":"4be6f045dbbf5041","repo":"phalcon/cphalcon","slug":"failed-to-store-metadata-to-the-cache-adapter","errorCode":null,"errorMessage":"Failed to store metaData to the cache adapter","messagePattern":"Failed to store metaData to the cache adapter","errorType":"exception","errorClass":"Phalcon\\Mvc\\Model\\MetaData\\Exceptions\\MetaDataStrategyFailed","httpStatus":null,"severity":"warning","filePath":"phalcon/Mvc/Model/MetaData.zep","lineNumber":1063,"sourceCode":"                    unset(this->pendingMetaDataWrites[key]);\n                }\n            }\n            return true;\n        }\n        return false;\n    }\n\n    /**\n     * Throws an exception when the metadata cannot be written\n     */\n    private function throwWriteException(var option) -> void\n    {\n        string message;\n\n        let message = \"Failed to store metaData to the cache adapter\";\n\n        if option {\n            throw new MetaDataStrategyFailed(message);\n        } else {\n            trigger_error(message);\n        }\n    }\n}\n","sourceCodeStart":1045,"sourceCodeEnd":1069,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Mvc/Model/MetaData.zep#L1045-L1069","documentation":"After metadata is computed on a cache miss, MetaData::write() persists it with adapter->set(key, data). If that call returns false or throws (backend down, wrong credentials, unwritable directory, oversized payload), write() consults the orm.exception_on_failed_metadata_save setting (also settable via Phalcon\\Mvc\\Model\\Model::setup(['exceptionOnFailedMetaDataSave' => ...])): with the setting enabled it throws MetaDataStrategyFailed, otherwise it raises a PHP warning via trigger_error(). The computed metadata still works in memory for the current request — only persistence failed.","triggerScenarios":"The first model query of a process after a deployment (cache miss triggers write) while the metadata backend refuses writes: Redis/Libmemcached unreachable or read-only, Stream adapter's metaDataDir lacking write permission or disk space, or an adapter whose set() returns false.","commonSituations":"Cache node restarts during deploys; container images where the metadata directory is read-only; permission changes on cache/metadata; transient network failures to Redis; enabling exceptionOnFailedMetaDataSave and then hitting a routine cache outage.","solutions":["Restore the backend: verify connectivity, credentials, and (for Stream) that the metadata directory exists, is writable, and has space.","Delete stale or poisoned 'meta-*' entries so the next write carries a clean payload.","If requests must survive cache outages, keep orm.exception_on_failed_metadata_save off (write failures then only warn) — but alert on the warning.","Match the adapter's serializer with what the backend supports on every node."],"exampleFix":"// before: Stream adapter writing to a read-only directory\n$metaData = new Phalcon\\Mvc\\Model\\MetaData\\Stream([\n    'metaDataDir' => '/var/www/app/config/', // not writable -> write fails\n]);\n\n// after\n$metaData = new Phalcon\\Mvc\\Model\\MetaData\\Stream([\n    'metaDataDir' => '/var/www/app/cache/metadata/', // writable, shipped empty\n]);","handlingStrategy":"fallback","validationCode":"// Pre-flight: prove the metadata backend accepts writes before the first model query\n$probe = new Phalcon\\Cache\\Adapter\\Redis($redisOptions); // same backend settings as MetaData\nif (!$probe->set('meta-healthcheck', 1)) {\n    $di->setShared('modelsMetadata', new Phalcon\\Mvc\\Model\\MetaData\\Memory());\n}","typeGuard":null,"tryCatchPattern":"use Phalcon\\Mvc\\Model\\MetaData\\Exceptions\\MetaDataStrategyFailed;\n\ntry {\n    $invoices = Invoices::find(); // first query computes and stores metadata\n} catch (MetaDataStrategyFailed $e) {\n    $logger->error('metadata backend write failed: ' . $e->getMessage());\n    $di->setShared('modelsMetadata', new Phalcon\\Mvc\\Model\\MetaData\\Memory()); // degrade gracefully\n    $invoices = Invoices::find();\n}","preventionTips":["Monitor cache backend health and disk space for Stream metadata directories.","Keep orm.exception_on_failed_metadata_save off unless cache outages should be hard failures.","Include a metadata write smoke check in deploy scripts and alert on trigger_error warnings."],"tags":["phalcon","orm","metadata","cache","configuration"],"backgroundTag":"cache-write-failure","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}