phalcon/cphalcon · error · UnrecognizedDataType

Unrecognized MySQL data type at column {}

Error message

Unrecognized MySQL data type at column {}

What it means

Mysql dialect's column-to-SQL compiler throws UnrecognizedDataType when a Phalcon\Db\Column object's type constant falls through the big switch in the default branch and no explicit column SQL was set. That happens when the Column was constructed with an unknown/newer TYPE_* constant, or with type 0 / a raw integer that matches no case; the dialect refuses to guess a MySQL type for the column.

Source

Thrown at phalcon/Db/Dialect/Mysql.zep:788

                break;

            case Column::TYPE_MULTIPOLYGON:
                if empty columnSql {
                    let columnSql .= "MULTIPOLYGON";
                }

                break;

            case Column::TYPE_GEOMETRYCOLLECTION:
                if empty columnSql {
                    let columnSql .= "GEOMETRYCOLLECTION";
                }

                break;

            default:
                if unlikely empty columnSql {
                    throw new UnrecognizedDataType("MySQL", column->getName());
                }

                let typeValues = column->getTypeValues();
                if !empty typeValues {
                    if typeof typeValues == "array" {
                        var value, valueSql;

                        let valueSql = "";

                        for value in typeValues {
                            let valueSql .= "\"" . addcslashes(value, "\"") . "\", ";
                        }

                        let columnSql .= "(" . substr(valueSql, 0, -2) . ")";
                    } else {
                        let columnSql .= "(\"" . addcslashes(typeValues, "\"") . "\")";
                    }
                }

View on GitHub (pinned to b7419de9cd)

Solutions

1. Use a type constant supported by the MySQL dialect, e.g. Column::TYPE_VARCHAR, TYPE_INTEGER, TYPE_TEXT, TYPE_JSON — check the constants on the Phalcon\Db\Column class you run
2. Never pass raw integers; always use the named TYPE_* constants so a mismatch surfaces at compile time
3. Guard the constants you use with a small mapping array validated per adapter before calling createTable()/addColumn()

Example fix

// before
$column = new Column('meta', ['type' => 999, 'size' => 10]);

// after
$column = new Column('meta', ['type' => Column::TYPE_VARCHAR, 'size' => 10]);

if (!in_array($column->getType(), $allowedMysqlTypes, true)) {
    throw new InvalidArgumentException('Column type not supported by the MySQL dialect: ' . $column->getName());
}

// Guard at construction: only named constants, never raw integers.
function mysqlColumn(string $name, array $definition): \Phalcon\Db\Column
{
    if (!isset($definition['type']) || !is_int($definition['type'])
        || $definition['type'] < 1) {
        throw new InvalidArgumentException("Invalid type for column {$name}");
    }
    return new \Phalcon\Db\Column($name, $definition);
}

try {
    $connection->createTable($table, null, $definition);
} catch (\Phalcon\Db\Exceptions\UnrecognizedDataType $e) {
    throw new RuntimeException("DDL rejected for {$table}: " . $e->getMessage(), 0, $e);
}

When it happens

Trigger: new Column('meta', ['type' => 999]) or a type constant not handled by the Mysql dialect (e.g. a type introduced for another backend, or TYPE_BIGINTEGER/SERIAL variants handled only after a match); creating tables or adding columns via $adapter->createTable()/addColumn() with such a Column; deserializing Column definitions where 'type' failed to map.

Common situations: Sharing column definition constants across dialects in multi-backend code; copying TYPE_* constants between Phalcon versions where new constants exist but the dialect branch does not cover them; passing getColumn() results between adapters of different versions.

Related errors

• The index 'columns' is required in the definition array
• Unrecognized PostgreSQL data type at column {}
• The table must contain at least one column
• The index 'sql' is required in the definition array
• The index 'columns' is required in the definition array

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