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

The base Grammar class's compileJoinLateral throws this as a default. Engine-specific grammars that support LATERAL joins (MySQL 8.0.14+, PostgreSQL, SQL Server) override it. SQLite and any custom grammar extending the base Grammar do not, so the throw fires. Lateral joins allow a subquery in a JOIN to reference columns from preceding tables in the FROM clause.

Solutions

1. Switch the connection to MySQL 8.0.14+, PostgreSQL, or SQL Server — all three override compileJoinLateral
2. Refactor the lateral join into a correlated subquery in the SELECT or WHERE clause to achieve the same result without LATERAL
3. In tests, use a pgsql or mysql Docker container instead of SQLite so lateral joins compile
4. If using a custom grammar, override compileJoinLateral in your grammar class to emit the correct SQL

Example fix

// before — lateral join fails on SQLite
$users = 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 — use a regular subquery join (works on all engines)
$sub = DB::table('orders')->select('user_id', DB::raw('SUM(total) as spent'))->groupBy('user_id');
$users = DB::table('users')->joinSub($sub, 'o', 'o.user_id', 'users.id')->get();

$connName = DB::connection()->getDriverName();
$supportsLateral = in_array($connName, ['mysql', 'pgsql', 'sqlsrv']);

if ($supportsLateral) {
    $query->joinSubLateral($sub, 'alias', 'a.id', '=', 'b.id');
} else {
    $query->joinSub($sub, 'alias', 'a.id', '=', 'b.id');
}

function supportsLateralJoins(): bool {
    $driver = DB::connection()->getDriverName();
    // MariaDB also reports as 'mysql' but lacks lateral — check driver name
    $isMaria = DB::connection() instanceof \Illuminate\Database\MariaDbConnection;
    return in_array($driver, ['mysql', 'pgsql', 'sqlsrv']) && ! $isMaria;
}

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;
    }
}

When it happens

Trigger: Calling joinSubLateral() or leftJoinSubLateral() on a query builder backed by a SQLite connection (e.g., during testing) or a custom database driver whose grammar extends Grammar without overriding compileJoinLateral.

Common situations: Using lateral joins in production with PostgreSQL but running the test suite against SQLite in-memory. Adding a custom database driver that extends the base Grammar class without implementing lateral join support.

Related errors

• This database engine does not support lateral joins.
• This database engine does not support straight joins.
• Database file at path
• Database was not created. Aborting migration.
• Index [ ] does not exist.

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

Appendix: source

Thrown at src/Illuminate/Database/Query/Grammars/Grammar.php:219

            $joinWord = ($join->type === 'straight_join' && $this->supportsStraightJoins()) ? '' : ' join';

            return trim("{$join->type}{$joinWord} {$tableAndNestedJoins} {$this->compileWheres($join)}");
        })->implode(' ');
    }

    /**
     * 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.');
    }

    /**
     * Determine if the grammar supports straight joins.
     *
     * @return bool
     *
     * @throws \RuntimeException
     */
    protected function supportsStraightJoins()
    {
        throw new RuntimeException('This database engine does not support straight joins.');
    }

    /**
     * Compile the "where" portions of the query.
     *
     * @param  \Illuminate\Database\Query\Builder  $query

View on GitHub (pinned to e0f6eb3518)