{"record":{"id":"10ae8778d1212bca","repo":"phalcon/cphalcon","slug":"invalid-meta-data-for-model-modelname","errorCode":null,"errorMessage":"Invalid meta-data for model {modelName}","messagePattern":"Invalid meta-data for model (.+?)","errorType":"exception","errorClass":"Phalcon\\Mvc\\Model\\MetaData\\Exceptions\\InvalidMetaDataForModel","httpStatus":null,"severity":"error","filePath":"phalcon/Mvc/Model/MetaData.zep","lineNumber":1009,"sourceCode":"\n            if false === isset(metaData[key]) {\n                /**\n                 * The meta-data is read from the adapter always if not available in metaData property\n                 */\n                let prefixKey = \"meta-\" . key,\n                    data = this->{\"read\"}(prefixKey);\n\n                if data !== null {\n                    let this->metaData[key] = data;\n                } else {\n                    /**\n                     * Check if there is a method 'metaData' in the model to retrieve meta-data from it\n                     */\n                    if method_exists(model, \"metaData\") {\n                        let modelMetadata = model->{\"metaData\"}();\n\n                        if unlikely typeof modelMetadata != \"array\" {\n                            throw new InvalidMetaDataForModel(get_class(model));\n                        }\n                    } else {\n                        /**\n                         * Get the meta-data extraction strategy\n                         */\n                        let container = this->getDI(),\n                            strategy = this->getStrategy(),\n                            modelMetadata = strategy->getMetaData(\n                                model,\n                                container\n                            );\n                    }\n\n                    /**\n                     * Store the meta-data locally\n                     */\n                    let this->metaData[key] = modelMetadata;\n","sourceCodeStart":991,"sourceCodeEnd":1027,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Mvc/Model/MetaData.zep#L991-L1027","documentation":"During a metadata cache miss, Phalcon checks whether the model class defines a metaData() method and, if so, uses its return value as the complete metadata record. That value must be an array keyed by Phalcon\\Mvc\\Model\\MetaData\\MetaData constants (MODELS_ATTRIBUTES, MODELS_DATA_TYPES, ...). If metaData() returns anything else — null, a string, a Generator — this exception is thrown with the model class name in the message.","triggerScenarios":"A model class defines public function metaData() whose execution returns a non-array: an uninitialized typed property returns null, an early return, a JSON/string payload, or an unrelated helper method that happens to be named metaData().","commonSituations":"Developers adding a metaData() method for logging, API payloads or documentation unrelated to ORM metadata; refactors that change the return type; static analyzers or lazily-initialized caches making the method return null on first call.","solutions":["Make metaData() return an array keyed by MetaData constants, with arrays for every index (null allowed only for the column-map indexes).","If the method was not meant to supply ORM metadata, rename it so Phalcon falls back to the Introspection/Annotations strategy.","Check for early returns or uninitialized properties that can make the method yield null.","Clear the metadata cache after fixing the method so the bad value is not sticky."],"exampleFix":"// before\nclass Invoices extends Model\n{\n    public function metaData()\n    {\n        return $this->cachedDescriptions; // null/string -> InvalidMetaDataForModel\n    }\n}\n\n// after\nclass Invoices extends Model\n{\n    public function metaData(): array\n    {\n        return [\n            MetaData::MODELS_ATTRIBUTES  => ['inv_id', 'inv_cst_id'],\n            MetaData::MODELS_PRIMARY_KEY => ['inv_id'],\n            // ... every required index as an array\n        ];\n    }\n}","handlingStrategy":"validation","validationCode":"if (method_exists($model, 'metaData') && !is_array($model->metaData())) {\n    throw new InvalidArgumentException(get_class($model) . '::metaData() must return an array');\n}","typeGuard":"function modelSuppliesValidMetaData(object $model): bool\n{\n    return !method_exists($model, 'metaData') || is_array($model->metaData());\n}","tryCatchPattern":"use Phalcon\\Mvc\\Model\\MetaData\\Exceptions\\InvalidMetaDataForModel;\n\ntry {\n    $metaData->getAttributes($model);\n} catch (InvalidMetaDataForModel $e) {\n    $metaData->reset(); // drop the poisoned attempt\n    throw $e;           // the model's metaData() must be fixed first\n}","preventionTips":["Reserve the method name metaData() exclusively for ORM metadata in Phalcon projects.","Add a static test asserting is_array($model->metaData()) for every model that defines it.","Prefer Introspection or annotations over hand-written metaData() unless you must control the shape."],"tags":["phalcon","orm","metadata","model-definition"],"backgroundTag":"model-metadata-invalid","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}