phalcon/cphalcon · error · Phalcon\DataMapper\Pdo\Exception\DriverNotSupported

Driver not supported [{driver}]

Error message

Driver not supported [{driver}]

What it means

Connection's constructor splits the DSN at the first colon and requires the prefix to be one of a hardcoded whitelist — mysql, pgsql, sqlite, mssql — checked before PDO is ever constructed. Any other prefix throws DriverNotSupported, even when the installed PDO supports it (sqlsrv, dblib, oci are all rejected here).

Source

Thrown at phalcon/DataMapper/Pdo/Connection.zep:66

        string username = null,
        string password = null,
        array options = [],
        array queries = [],
        <ProfilerInterface> profiler = null
    ) {
        var parts;
        array available;

        let parts     = explode(":", dsn),
            available = [
                "mysql"  : true,
                "pgsql"  : true,
                "sqlite" : true,
                "mssql"  : true
            ];

        if !isset available[parts[0]] {
            throw new DriverNotSupported(parts[0]);
        }


        // if no error mode is specified, use exceptions
        if !isset options[\PDO::ATTR_ERRMODE] {
            let options[\PDO::ATTR_ERRMODE] = \PDO::ERRMODE_EXCEPTION;
        }

        // Arguments store
        let this->arguments = [
            dsn,
            username,
            password,
            options,
            queries
        ];

        // Create a new profiler if none has been passed

View on GitHub (pinned to b7419de9cd)

Solutions

1. Use a whitelisted prefix (mysql, pgsql, sqlite, mssql) — for SQL Server over dblib the expected key here is 'mssql'
2. For other drivers, construct \PDO yourself and wrap it with Connection\Decorated, which skips the DSN check
3. Extend Connection and override the whitelist if you must support sqlsrv/oci natively
4. Validate the DSN prefix in your config layer at boot so it fails with a clear message before any connection attempt

Example fix

// before
$conn = new Connection('sqlsrv:Server=db;Database=x', 'user', 'pass'); // DriverNotSupported

// after
$pdo = new \PDO('sqlsrv:Server=db;Database=x', 'user', 'pass');
$conn = new \Phalcon\DataMapper\Pdo\Connection\Decorated($pdo);

const SUPPORTED_DSN_PREFIXES = ['mysql', 'pgsql', 'sqlite', 'mssql'];

$prefix = strtolower(explode(':', $dsn, 2)[0]);
if (!in_array($prefix, SUPPORTED_DSN_PREFIXES, true)) {
    throw new InvalidArgumentException(
        "DSN driver '{$prefix}' is not supported by Connection; supported: "
        . implode(', ', SUPPORTED_DSN_PREFIXES)
    );
}
return new Connection($dsn, $username, $password, $options);

use Phalcon\DataMapper\Pdo\Exception\DriverNotSupported;

try {
    $connection = new Connection($dsn, $username, $password);
} catch (DriverNotSupported $e) {
    $pdo = new \PDO($dsn, $username, $password);
    $connection = new \Phalcon\DataMapper\Pdo\Connection\Decorated($pdo);
}

When it happens

Trigger: new Connection('sqlsrv:Server=host;Database=x', ...) or 'dblib:...' for SQL Server; 'oci:...' for Oracle; a DSN with a typo'd prefix ('mysl:'); a DSN missing the colon so the whole string becomes the prefix.

Common situations: SQL Server deployments (pdo_sqlsrv/pdo_dblib) or Oracle deployments where the real PDO driver name is not in the whitelist; DSNs assembled from config where the driver key is empty or user-edited.

Related errors

• Class '{className}' does not have a method '{name}'
• Cannot disconnect a Decorated connection instance
• Connection not found: {type}:{requested}
• Operation cancelled by a listener of '{eventName}'
• Invalid bind parameter (1)

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