laravel/framework · error · RuntimeException

This database engine does not support lateral joins.

Error message

This database engine does not support lateral joins.

What it means

MariaDbGrammar explicitly overrides compileJoinLateral to throw, even though it extends MySqlGrammar (which implements lateral joins). MariaDB does not support LATERAL joins as of its current stable releases, so the framework enforces this limitation at compile time rather than letting invalid SQL reach the server.

Solutions

  1. Switch to MySQL 8.0.14+ (change DB_CONNECTION/driver from mariadb to mysql) which supports lateral joins
  2. Refactor the lateral join into a correlated subquery in a regular joinSub() — functionally equivalent without LATERAL
  3. Use a window function or CTE approach to avoid needing a lateral join altogether
  4. Switch to PostgreSQL which also supports lateral joins

Example fix

// before — fails on MariaDB
DB::table('users')
    ->joinSubLateral(
        DB::table('orders')->select('user_id', DB::raw('SUM(total) as spent'))->groupBy('user_id'),
        'o', 'o.user_id', 'users.id'
    )->get();

// after — joinSub works on MariaDB (no LATERAL needed here)
DB::table('users')
    ->joinSub(
        DB::table('orders')->select('user_id', DB::raw('SUM(total) as spent'))->groupBy('user_id'),
        'o', 'o.user_id', 'users.id'
    )->get();
Defensive patterns

Strategy: type-guard

Validate before calling

$conn = DB::connection();
$isMaria = $conn instanceof \Illuminate\Database\MariaDbConnection;

if (! $isMaria) {
    $query->joinSubLateral($sub, 'o', 'o.user_id', 'users.id');
} else {
    // MariaDB lacks LATERAL — use regular joinSub
    $query->joinSub($sub, 'o', 'o.user_id', 'users.id');
}

Type guard

function supportsLateralJoins(): bool {
    $conn = DB::connection();
    $isMaria = $conn instanceof \Illuminate\Database\MariaDbConnection;
    $isSupportedDriver = in_array($conn->getDriverName(), ['mysql', 'pgsql', 'sqlsrv']);
    return $isSupportedDriver && ! $isMaria;
}

Try / catch

try {
    $query->joinSubLateral($sub, 'o', 'o.user_id', 'users.id');
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'lateral joins')) {
        $query->joinSub($sub, 'o', 'o.user_id', 'users.id');
    } else {
        throw $e;
    }
}

Prevention

When it happens

Trigger: Calling joinSubLateral() or leftJoinSubLateral() on a query builder whose connection uses MariaDbGrammar (configured as 'mariadb' driver). For example: DB::table('users')->joinSubLateral($sub, 'o', 'o.user_id', 'users.id')->get().

Common situations: Using MariaDB as the primary database while developing features that use lateral joins (which work on MySQL 8+). Confusion between MySQL and MariaDB feature sets — lateral joins are MySQL-only and explicitly blocked on MariaDB.

Related errors

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

Appendix: source

Thrown at src/Illuminate/Database/Query/Grammars/MariaDbGrammar.php:22

use Illuminate\Database\Query\Builder;
use Illuminate\Database\Query\JoinLateralClause;
use RuntimeException;

class MariaDbGrammar extends MySqlGrammar
{
    /**
     * Compile a "lateral join" clause.
     *
     * @param  \Illuminate\Database\Query\JoinLateralClause  $join
     * @param  string  $expression
     * @return string
     *
     * @throws \RuntimeException
     */
    public function compileJoinLateral(JoinLateralClause $join, string $expression): string
    {
        throw new RuntimeException('This database engine does not support lateral joins.');
    }

    /**
     * Compile a "JSON value cast" statement into SQL.
     *
     * @param  string  $value
     * @return string
     */
    public function compileJsonValueCast($value)
    {
        return "json_query({$value}, '$')";
    }

    /**
     * Compile a query to get the number of open connections for a database.
     *
     * @return string
     */

View on GitHub (pinned to e0f6eb3518)