What causes "Database hosts array is empty." in laravel/framework?

Set DB_HOST in .env (e.g. DB_HOST=127.0.0.1) and confirm it is read by config/database.php.

laravel/framework · error · InvalidArgumentException

Database hosts array is empty.

Error message

Database hosts array is empty.

What it means

Thrown by ConnectionFactory::parseHosts() when Arr::wrap($config['host']) is empty. The factory iterates the hosts array to build a read/write PDO resolver per host, so an empty list (missing host, blank string, or empty array) is rejected before any connection attempt. SQLite connections are exempt because they go through a host-less resolver path.

Solutions

Set DB_HOST in .env (e.g. DB_HOST=127.0.0.1) and confirm it is read by config/database.php.
Ensure the 'host' key in the connection config is a non-empty string or a non-empty array.
For socket-only MySQL, set the host to 'localhost' and configure the unix_socket option rather than leaving host blank.
If you intentionally have no host (SQLite), set the connection driver to 'sqlite' so parseHosts is not invoked.

Example fix

// before (config/database.php)
'mysql' => ['driver' => 'mysql', 'host' => env('DB_HOST') /* empty */],

// after
'mysql' => ['driver' => 'mysql', 'host' => env('DB_HOST', '127.0.0.1')],

Defensive patterns

Strategy: validation

Validate before calling

$hosts = \Illuminate\Support\Arr::wrap($config['host'] ?? null);
if (empty($hosts) || array_filter($hosts) === []) {
    throw new \InvalidArgumentException('DB host missing: set DB_HOST.');
}

Type guard

function hasNonEmptyHost(array $config): bool {
    $hosts = \Illuminate\Support\Arr::wrap($config['host'] ?? null);
    return ! empty(array_filter($hosts));
}

Prevention

Always provide a fallback default in config: 'host' => env('DB_HOST', '127.0.0.1').
Fail fast in CI by asserting DB_HOST is non-empty before bootstrapping the app.
For SQLite, use the 'sqlite' driver so the host parser is bypassed.

When it happens

Trigger: A connection config where 'host' is missing, set to '' (which Arr::wrap keeps as a one-element empty array after trimming in some paths), or set to []. Triggered when DatabaseManager/Capsule first builds the connection.

Common situations: .env with DB_HOST empty or unset for a mysql/pgsql/sqlsrv connection; config/database.php 'host' => env('DB_HOST') resolving to null; multiple-host config with all entries removed; deploying without copying .env.

Related errors

AI-assisted analysis of laravel/framework@e0f6eb3518 (2026-08-11). Data as JSON: /api/errors/3da5627d6fcdc23f. Report an issue: GitHub.

Appendix: source

Thrown at src/Illuminate/Database/Connectors/ConnectionFactory.php:245

                throw $exception;
            }
        };
    }

    /**
     * Parse the hosts configuration item into an array.
     *
     * @param  array  $config
     * @return array
     *
     * @throws \InvalidArgumentException
     */
    protected function parseHosts(array $config)
    {
        $hosts = Arr::wrap($config['host']);

        if (empty($hosts)) {
            throw new InvalidArgumentException('Database hosts array is empty.');
        }

        return $hosts;
    }

    /**
     * Create a new Closure that resolves to a PDO instance where there is no configured host.
     *
     * @param  array  $config
     * @return \Closure
     */
    protected function createPdoResolverWithoutHosts(array $config)
    {
        return fn () => $this->createConnector($config)->connect($config);
    }

    /**
     * Create a connector instance based on the configuration.

View on GitHub (pinned to e0f6eb3518)