phalcon/cphalcon · error · Phalcon\Mvc\Model\Exceptions\IdentityNotInColumnMap

Identity column '{identityField}' isn't part of the column m

Error message

Identity column '{identityField}' isn't part of the column map in '{className}'

What it means

Thrown by Model::doLowInsert() (phalcon/Mvc/Model.zep:4239) when the model has an identity (auto-increment/sequence) column and that column is absent from the model's column map. The exception class is Phalcon\Mvc\Model\Exceptions\IdentityNotInColumnMap. It fires even before any value check, so any insert on such a model fails immediately.

Source

Thrown at phalcon/Mvc/Model.zep:4239

        if identityField !== false {
            let defaultValue = connection->getDefaultIdValue();

            /**
             * Not all the database systems require an explicit value for
             * identity columns
             */
            let useExplicitIdentity = (bool) connection->useExplicitIdValue();

            if useExplicitIdentity {
                let fields[] = identityField;
            }

            /**
             * Check if the model has a column map
             */
            if typeof columnMap == "array" {
                if unlikely !fetch attributeField, columnMap[identityField] {
                    throw new IdentityNotInColumnMap(identityField, get_class(this));
                }
            } else {
                let attributeField = identityField;
            }

            /**
             * Check if the developer set an explicit value for the column
             */
            if fetch value, this->{attributeField} {
                if value === null || value === "" {
                    if useExplicitIdentity {
                        let values[] = defaultValue, bindTypes[] = bindSkip;
                    } elseif empty values {
                        /**
                         * Model has only the identity column; force an
                         * explicit default so the underlying adapter does not
                         * reject the insert because of an empty values array.
                         */

View on GitHub (pinned to b7419de9cd)

Solutions

1. Add the identity column as a key in columnMap(), e.g. return ['the_id' => 'id', ...]
2. If the PK was renamed in the table, update both the columnMap() key and any model code referencing the property
3. Clear metadata cache to make sure the identity field name reported by metadata matches the columnMap key

Example fix

// before
public function columnMap()
{
    return ['name' => 'name', 'total' => 'total']; // 'invoice_id' identity omitted
}
// (new Invoice())->save(); // IdentityNotInColumnMap

// after
public function columnMap()
{
    return [
        'invoice_id' => 'id',
        'name'      => 'name',
        'total'     => 'total',
    ];
}

$metaData = $model->getModelsMetaData();
$map = $metaData->getColumnMap($model);
$identity = $metaData->getIdentityField($model);
if (is_array($map) && $identity && !isset($map[$identity])) {
    // identity column missing from columnMap(): fix the map before save()
    throw new RuntimeException("columnMap lacks identity '{$identity}'");
}

When it happens

Trigger: A model with a columnMap() that maps all data columns but forgets the primary key / identity column, followed by save()/create(). Also when the identity field name changed in the table (e.g. 'id' -> 'invoice_id') but the column map still uses the old key.

Common situations: Copy-pasting a columnMap() from another model and dropping the PK entry; renaming the PK column in a migration without updating columnMap(); composite or unusual PK names that the developer assumed were implicit.

Related errors

• Identity column '{identityField}' isn't part of the table co
• Column '{column}' isn't part of the table columns in '{class
• Class '{className}' is not an ADR Action.
• Unable to insert into {table} without data
• Incomplete number of bind types

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