laravel/framework · error · InvalidArgumentException

Database hosts array is empty.

Error message

Database hosts array is empty.

What it means

Thrown by ConnectionFactory::parseHosts() when the 'host' config key resolves to an empty array (Arr::wrap on null or empty string yields an empty array). The factory builds a read/write resolver that needs at least one host to try.

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 bd6b5437e6)

Solutions

1. Set the DB_HOST (and DB_READ_HOST / DB_WRITE_HOST if using a split) environment variable.
2. Verify config/database.php has a non-empty 'host' key under the connection and any read/write sub-arrays.
3. Run php artisan config:cache after fixing .env so the cached config is rebuilt.
4. Validate the resolved config at boot: assert !empty(config('database.connections.mysql.host')).

Example fix

// before (.env)
DB_HOST=

// after
DB_HOST=127.0.0.1

$cfg = config('database.connections.'.$name);
foreach (Arr::wrap($cfg['host'] ?? null) as $h) {
    if (empty($h)) {
        throw new \RuntimeException("Connection [$name] has an empty host.");
    }
}

function hasNonEmptyHosts(array $config): bool {
    return ! empty(Arr::wrap($config['host'] ?? null));
}

When it happens

Trigger: A connection config that has read/write sub-configs (or a host array) but no actual host value, e.g. ['driver'=>'mysql','host'=>null,'read'=>['host'=>null],'write'=>['host'=>[]]]. Triggered when ConnectionFactory::createReadPdoResolverWithHosts() calls parseHosts() on a read/write split setup.

Common situations: Missing DB_HOST env var in a read/write split; typo'd key (hostname vs host); empty string host coming from .env; deploying to an environment that didn't set the host var.

Related errors

• A driver must be specified.
• Broadcast connection [{$name}] is not defined.
• Lost connection and no reconnector available.
• Unsupported driver [{$config['driver']}].
• Unsupported driver [{$driver}].

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/3da5627d6fcdc23f.json. Report an issue: GitHub.