phalcon/cphalcon · critical · MissingSqliteDatabase

The database must be specified with either 'dbname' or 'dsn'

Error message

The database must be specified with either 'dbname' or 'dsn'.

What it means

Phalcon\Db\Adapter\Pdo\Sqlite::connect() must know where the SQLite database lives. The descriptor has to provide either 'dbname' (a file path, or ':memory:') or a ready-made 'dsn'; 'dbname' is rewritten into the DSN automatically. With neither key present the adapter throws MissingSqliteDatabase before PDO is constructed - SQLite has no server to contact, so the database target is mandatory.

Source

Thrown at phalcon/Db/Adapter/Pdo/Sqlite.zep:81

    /**
     * This method is automatically called in Phalcon\Db\Adapter\Pdo
     * constructor. Call it when you need to restore a database connection.
     */
    public function connect( array descriptor = []) -> void
    {
        var dbname;

        if empty descriptor {
            let descriptor = this->descriptor;
        }

        if fetch dbname, descriptor["dbname"] {
            let descriptor["dsn"] = dbname;

            unset descriptor["dbname"];
        } elseif unlikely !isset descriptor["dsn"] {
            throw new MissingSqliteDatabase();
        }

        parent::connect(descriptor);
    }

    /**
     * Returns an array of Phalcon\Db\Column objects describing a table
     *
     * ```php
     * print_r(
     *     $connection->describeColumns("posts")
     * );
     * ```
     */
    public function describeColumns( string table,  string schema = null) -> <ColumnInterface[]>
    {
        var columns, columnType, fields, field, definition, oldColumn,
            sizePattern, matches, matchOne, matchTwo, columnName, hiddenFlag;

View on GitHub (pinned to b7419de9cd)

Solutions

1. Add 'dbname' => '/path/to/app.sqlite' (or ':memory:' for an in-memory database) to the descriptor.
2. Alternatively pass a complete 'dsn' => 'sqlite:/path/to/app.sqlite'.
3. If the path comes from an env var, verify it resolves (getenv() !== false) before constructing the adapter.

Example fix

// before
$connection = new Pdo\Sqlite(['adapter' => 'sqlite']); // throws MissingSqliteDatabase

// after
$connection = new Pdo\Sqlite([
    'adapter' => 'sqlite',
    'dbname'  => '/var/data/app.sqlite',
]);
// or: new Pdo\Sqlite(['dsn' => 'sqlite:/var/data/app.sqlite']);

if (!isset($descriptor['dbname']) && !isset($descriptor['dsn'])) {
    throw new InvalidArgumentException('SQLite descriptor requires "dbname" or "dsn"');
}
$connection = new Pdo\Sqlite($descriptor);

function sqliteDescriptorIsConnectable(array $descriptor): bool
{
    return isset($descriptor['dbname']) || isset($descriptor['dsn']);
}

use Phalcon\Db\Exceptions\MissingSqliteDatabase;

try {
    $connection = new Pdo\Sqlite($descriptor);
} catch (MissingSqliteDatabase $e) {
    // Fail loudly at boot with a config-oriented message
    throw new RuntimeException('DB config incomplete: set SQLITE_DB_PATH', 0, $e);
}

When it happens

Trigger: new Pdo\Sqlite(['adapter' => 'sqlite']) with nothing else; descriptors reusing MySQL-style keys ('host', 'username') without 'dbname'; a typo'd key like 'database' instead of 'dbname'; env-driven config where the path variable is unset so the key never lands in the descriptor; calling connect() again with an empty descriptor.

Common situations: Switching an app from the MySQL adapter to SQLite in config and forgetting the path; multi-environment setups where SQLite is only used in tests and the test env var is missing in CI; copy-pasted config snippets from other adapters; refactors renaming descriptor keys.

Related errors

• Malformed ACL snapshot structure
• ON CONFLICT requires at least one conflict-target column
• The index 'columns' is required in the definition array
• The index 'sql' is required in the definition array
• Dropping a CHECK constraint is not supported by SQLite

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