{"id":"0b49c6adb21acea4","repo":"laravel/framework","slug":"the-returning-columns-must-not-be-empty","errorCode":null,"errorMessage":"The returning columns must not be empty.","messagePattern":"The returning columns must not be empty\\.","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Database/Query/Builder.php","lineNumber":4217,"sourceCode":"    /**\n     * Insert new records into the database and returning specified columns with optional ignoring specific conflicts.\n     *\n     * @param  non-empty-array<non-empty-string>  $returning\n     * @param  non-empty-string|non-empty-array<non-empty-string>|null  $uniqueBy\n     * @return \\Illuminate\\Support\\Collection\n     */\n    public function insertOrIgnoreReturning(array $values, array $returning = ['*'], array|string|null $uniqueBy = null)\n    {\n        if (empty($values)) {\n            return new Collection;\n        }\n\n        if ($uniqueBy === [] || $uniqueBy === '') {\n            throw new InvalidArgumentException('The unique columns must not be empty.');\n        }\n\n        if ($returning === []) {\n            throw new InvalidArgumentException('The returning columns must not be empty.');\n        }\n\n        if (! is_array(array_first($values))) {\n            $values = [$values];\n        } else {\n            foreach ($values as $key => $value) {\n                ksort($value);\n\n                $values[$key] = $value;\n            }\n        }\n\n        $this->applyBeforeQueryCallbacks();\n\n        $sql = $this->grammar->compileInsertOrIgnoreReturning($this, $values, $returning, $uniqueBy === null ? null : Arr::wrap($uniqueBy));\n\n        $result = new Collection(\n            $this->connection->selectFromWriteConnection($sql, $this->cleanBindings(Arr::flatten($values, 1)))","sourceCodeStart":4199,"sourceCodeEnd":4235,"githubUrl":"https://github.com/laravel/framework/blob/bd6b5437e6ad87bb49f9b426724f07a9f64e9683/src/Illuminate/Database/Query/Builder.php#L4199-L4235","documentation":"Thrown by insertOrIgnoreReturning when $returning is an empty array `[]`. The default value is ['*'], but if a caller explicitly passes [] the method has nothing to RETURN (Postgres RETURNING clause requires at least one column), so it aborts. Returning columns are how the caller learns which rows were actually inserted versus ignored.","triggerScenarios":"Calling `insertOrIgnoreReturning($values, [])`. Building $returning from `array_intersect($allCols, $allowedCols)` when $allowedCols yields no matches. Copy-paste from insert() (which has no returning param) leaving an empty array literal.","commonSituations":"Allowlist filtering that produces an empty set; column-permission layers stripping all columns; refactoring where the returning list was optional but the signature now requires it.","solutions":["Pass `['*']` to return all columns: `insertOrIgnoreReturning($values, ['*'], $uniqueBy)`.","Pass at least one real column: `['id']` is usually sufficient to identify inserted rows.","Validate the allowlist result: `if (!$cols) $cols = ['id'];`.","If you genuinely do not need returned rows, use `insertOrIgnore()` instead."],"exampleFix":"// before\n$rows = DB::table('users')->insertOrIgnoreReturning($values, [], 'email');\n// => The returning columns must not be empty.\n\n// after\n$rows = DB::table('users')->insertOrIgnoreReturning($values, ['id','email'], 'email');","handlingStrategy":"validation","validationCode":"if ($returning === []) {\n    $returning = ['*'];\n}\n$table->insertOrIgnoreReturning($values, $returning, $uniqueBy);","typeGuard":"/** @param non-empty-array<non-empty-string> $r */\nfunction isValidReturning(array $r): bool\n{\n    return $r !== [] && array_all($r, fn($v) => is_string($v) && $v !== '');\n}","tryCatchPattern":"// Validate the returning list before the call. Use insertOrIgnore() if no return rows are needed.","preventionTips":["Default $returning to ['*'] or ['id'] in repository methods.","Validate allowlist filters so they never reduce to an empty list.","Document the non-empty requirement in the helper's docblock."],"tags":["query-builder","insert","returning","invalid-argument"],"analyzedSha":"bd6b5437e6ad87bb49f9b426724f07a9f64e9683","analyzedAt":"2026-08-06T00:28:32.783Z","schemaVersion":2}