What causes "Invalid meta-data for model {modelName}" in phalcon/cphalcon?

Make metaData() return an array keyed by MetaData constants, with arrays for every index (null allowed only for the column-map indexes).

phalcon/cphalcon · error · Phalcon\Mvc\Model\MetaData\Exceptions\InvalidMetaDataForModel

Invalid meta-data for model {modelName}

Error message

Invalid meta-data for model {modelName}

What it means

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.

Source

Thrown at phalcon/Mvc/Model/MetaData.zep:1009

            if false === isset(metaData[key]) {
                /**
                 * The meta-data is read from the adapter always if not available in metaData property
                 */
                let prefixKey = "meta-" . key,
                    data = this->{"read"}(prefixKey);

                if data !== null {
                    let this->metaData[key] = data;
                } else {
                    /**
                     * Check if there is a method 'metaData' in the model to retrieve meta-data from it
                     */
                    if method_exists(model, "metaData") {
                        let modelMetadata = model->{"metaData"}();

                        if unlikely typeof modelMetadata != "array" {
                            throw new InvalidMetaDataForModel(get_class(model));
                        }
                    } else {
                        /**
                         * Get the meta-data extraction strategy
                         */
                        let container = this->getDI(),
                            strategy = this->getStrategy(),
                            modelMetadata = strategy->getMetaData(
                                model,
                                container
                            );
                    }

                    /**
                     * Store the meta-data locally
                     */
                    let this->metaData[key] = modelMetadata;

View on GitHub (pinned to b7419de9cd)

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.

Example fix

// before
class Invoices extends Model
{
    public function metaData()
    {
        return $this->cachedDescriptions; // null/string -> InvalidMetaDataForModel
    }
}

// after
class Invoices extends Model
{
    public function metaData(): array
    {
        return [
            MetaData::MODELS_ATTRIBUTES  => ['inv_id', 'inv_cst_id'],
            MetaData::MODELS_PRIMARY_KEY => ['inv_id'],
            // ... every required index as an array
        ];
    }
}

Defensive patterns

Strategy: validation

Validate before calling

if (method_exists($model, 'metaData') && !is_array($model->metaData())) {
    throw new InvalidArgumentException(get_class($model) . '::metaData() must return an array');
}

Type guard

function modelSuppliesValidMetaData(object $model): bool
{
    return !method_exists($model, 'metaData') || is_array($model->metaData());
}

Try / catch

use Phalcon\Mvc\Model\MetaData\Exceptions\InvalidMetaDataForModel;

try {
    $metaData->getAttributes($model);
} catch (InvalidMetaDataForModel $e) {
    $metaData->reset(); // drop the poisoned attempt
    throw $e;           // the model's metaData() must be fixed first
}

Prevention

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.

When it happens

Trigger: 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().

Common situations: 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.

Related errors

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