laravel/framework · error · RuntimeException

This database engine does not support insert or ignore with…

Error message

This database engine does not support insert or ignore with returning.

What it means

The base Grammar's compileInsertOrIgnoreReturning throws by default. Only PostgresGrammar and SQLiteGrammar override it (using INSERT ... ON CONFLICT DO NOTHING RETURNING / INSERT OR IGNORE ... RETURNING). MySqlGrammar/MariaDbGrammar and SqlServerGrammar do not override it, so calling insertOrIgnore with a returning clause on MySQL or SQL Server triggers the throw. MySQL's INSERT IGNORE does not support a RETURNING clause.

Solutions

Switch to a PostgreSQL or SQLite connection — the only grammars that override compileInsertOrIgnoreReturning
On MySQL, drop the returning parameter and call insertOrIgnore() without it, then use lastInsertId() or a follow-up SELECT to retrieve inserted rows
On MySQL, use upsert() without a returning clause if you need insert-or-update semantics
On MySQL 8.0+, use a raw INSERT ... ON DUPLICATE KEY UPDATE statement and SELECT the affected rows afterward

Example fix

// before — fails on MySQL (RETURNING not supported)
$id = DB::table('users')->insertOrIgnore(['email' => 'a@b.com'], returning: ['id']);

// after — omit returning, retrieve ID separately
DB::table('users')->insertOrIgnore(['email' => 'a@b.com']);
$id = DB::table('users')->where('email', 'a@b.com')->value('id');

Defensive patterns

Strategy: type-guard

Validate before calling

$driver = DB::connection()->getDriverName();

if (in_array($driver, ['pgsql', 'sqlite'])) {
    $id = DB::table('users')->insertOrIgnore($values, returning: ['id']);
} else {
    // MySQL / SQL Server: omit returning, query afterward
    DB::table('users')->insertOrIgnore($values);
    $id = DB::table('users')->where('email', $values['email'])->value('id');
}

Type guard

function supportsInsertOrIgnoreReturning(): bool {
    return in_array(DB::connection()->getDriverName(), ['pgsql', 'sqlite']);
}

Try / catch

try {
    $result = DB::table('users')->insertOrIgnore($values, returning: ['id']);
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'insert or ignore with returning')) {
        DB::table('users')->insertOrIgnore($values);
        $result = DB::table('users')->where('email', $values['email'])->value('id');
    } else {
        throw $e;
    }
}

Prevention

Treat the returning parameter on insertOrIgnore as PostgreSQL/SQLite-only
On MySQL, plan to retrieve IDs with a follow-up query
Document RETURNING clause support per engine in project docs

When it happens

Trigger: Calling ->insertOrIgnore($values, returning: ['id']) or using the returning parameter on a MySQL, MariaDB, or SQL Server connection.

Common situations: Developer assumes MySQL INSERT IGNORE supports RETURNING (it does not — RETURNING is PostgreSQL/SQLite-specific). Code written for PostgreSQL deployed on MySQL.

Related errors

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

Appendix: source

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

    public function compileInsertOrIgnore(Builder $query, array $values)
    {
        throw new RuntimeException('This database engine does not support inserting while ignoring errors.');
    }

    /**
     * Compile an insert or ignore statement with a returning clause into SQL.
     *
     * @param  \Illuminate\Database\Query\Builder  $query
     * @param  array  $values
     * @param  array  $returning
     * @param  array|null  $uniqueBy
     * @return string
     *
     * @throws \RuntimeException
     */
    public function compileInsertOrIgnoreReturning(Builder $query, array $values, array $returning, ?array $uniqueBy)
    {
        throw new RuntimeException('This database engine does not support insert or ignore with returning.');
    }

    /**
     * Compile an insert and get ID statement into SQL.
     *
     * @param  \Illuminate\Database\Query\Builder  $query
     * @param  array  $values
     * @param  string|null  $sequence
     * @return string
     */
    public function compileInsertGetId(Builder $query, $values, $sequence)
    {
        return $this->compileInsert($query, $values);
    }

    /**
     * Compile an insert statement using a subquery into SQL.
     *

View on GitHub (pinned to e0f6eb3518)