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

Identity column '{identityField}' isn't part of the table co

Error message

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

What it means

Thrown by Model::doLowInsert() (phalcon/Mvc/Model.zep:4275) when the developer supplied an explicit non-empty value for the identity column and metaData->getBindTypes() has no bind type for it. The exception class is Phalcon\Mvc\Model\Exceptions\IdentityNotInTableColumns. It only triggers on the explicit-value branch, i.e. when you insert your own PK value.

Source

Thrown at phalcon/Mvc/Model.zep:4275

                         */
                        let fields[]    = identityField,
                            values[]    = defaultValue,
                            bindTypes[] = bindSkip;
                    }
                } else {
                    /**
                     * Add the explicit value to the field list if the user has
                     * defined a value for it
                     */
                    if !useExplicitIdentity {
                        let fields[] = identityField;
                    }

                    /**
                     * The field is valid we look for a bind value (normally int)
                     */
                    if unlikely !fetch bindType, bindDataTypes[identityField] {
                        throw new IdentityNotInTableColumns(identityField, get_class(this));
                    }

                    let values[]    = value,
                        bindTypes[] = bindType;
                }
            } else {
                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.
                     */
                    let fields[]    = identityField,
                        values[]    = defaultValue,
                        bindTypes[] = bindSkip;

View on GitHub (pinned to b7419de9cd)

Solutions

Clear/flush the model metadata cache so bind types are re-introspected with the identity column
In a custom metadata provider, add the identity field to getBindTypes() (BIND_PARAM_INT for numeric PKs, BIND_PARAM_STR for UUIDs)
If the explicit value is unintended, remove the assignment and let the DB generate the identity value

Example fix

// before
$invoice = new Invoice();
$invoice->id = 1234; // explicit identity
$invoice->save(); // IdentityNotInTableColumns

// after
// 1) flush metadata cache, or 2) fix provider:
// 'bindTypes' => ['id' => Column::BIND_PARAM_INT, 'name' => Column::BIND_PARAM_STR, ...]
$invoice->save();

Defensive patterns

Strategy: validation

Validate before calling

$metaData = $model->getModelsMetaData();
$identity = $metaData->getIdentityField($model);
$bindTypes = $metaData->getBindTypes($model);
if ($identity && !isset($bindTypes[$identity])) {
    $metaData->reset(); // re-introspect before explicit-PK insert
}

Prevention

Flush metadata after changing PK type or name
Keep one source-of-truth array in custom metadata for attributes, dataTypes, bindTypes and primaryKeys
In integration tests, insert one row with an explicit PK value to exercise this path

When it happens

Trigger: Setting $model->id = 123 (explicit PK) and saving, while bind-types metadata lacks the identity field. Common when metadata was cached before the PK column existed or was altered, or when a manual metadata provider omits the identity column from getBindTypes().

Common situations: Importing rows with fixed IDs into a table whose metadata cache is stale; custom metadata classes that list bind types only for non-PK columns; switching the identity column type (int -> uuid string) in the DB without refreshing metadata.

Related errors

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