laravel/framework · error · InvalidArgumentException

Order direction must be a SortDirection, "asc" or "desc".

Error message

Order direction must be a SortDirection, "asc" or "desc".

What it means

orderBy() now normalizes direction through a match expression. It accepts a SortDirection enum, or the case-insensitive strings 'asc'/'desc'; the default arm throws InvalidArgumentException. Earlier forms (integers, 'ascending', custom strings) are no longer tolerated.

Solutions

1. Whitelist and translate user input before it reaches orderBy: $dir = in_array($input, ['asc','desc'], true) ? $input : 'asc'.
2. Use the SortDirection enum for type safety in PHP 8.1+ code.
3. Reject or normalize unknown sort values at the controller/validation layer.

Example fix

// before
->orderBy('created_at', $request->sort)  // 'ascending', 'newest', etc.

// after
$dir = strtolower($request->sort) === 'desc' ? 'desc' : 'asc';
->orderBy('created_at', $dir)

$dir = in_array(strtolower((string) $input), ['asc', 'desc'], true)
    ? strtolower($input)
    : 'asc';
$query->orderBy($column, $dir);

When it happens

Trigger: ->orderBy('created_at', 'ascending'), ->orderBy('name', 1), ->orderBy('col', strtoupper($input)) where $input is neither 'ASC' nor 'DESC'.

Common situations: Front-end filter params sent straight into orderBy; legacy code passing 'ascending'/'descending' words or boolean/int flags; user-typed sort values from a query string.

Related errors

• Invalid binding type
• The chunk size should be at least 1
• The number of columns must match the number of values
• You must specify an orderBy clause when using this function.
• A subquery must be a query builder instance, a Closure, or…

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

Appendix: source

Thrown at src/Illuminate/Database/Query/Builder.php:2992

     */
    public function orderBy($column, $direction = SortDirection::Ascending)
    {
        if ($this->isQueryable($column)) {
            [$query, $bindings] = $this->createSub($column);

            $column = new Expression('('.$query.')');

            $this->addBinding($bindings, $this->unions ? 'unionOrder' : 'order');
        }

        $direction = match (true) {
            $direction instanceof SortDirection => match ($direction) {
                SortDirection::Ascending => 'asc',
                SortDirection::Descending => 'desc',
            },
            strtolower($direction) === 'asc' => 'asc',
            strtolower($direction) === 'desc' => 'desc',
            default => throw new InvalidArgumentException('Order direction must be a SortDirection, "asc" or "desc".'),
        };

        $this->{$this->unions ? 'unionOrders' : 'orders'}[] = [
            'column' => $column,
            'direction' => $direction,
        ];

        return $this;
    }

    /**
     * Add a descending "order by" clause to the query.
     *
     * @param  \Closure|\Illuminate\Database\Query\Builder|\Illuminate\Database\Eloquent\Builder<*>|\Illuminate\Contracts\Database\Query\Expression|string  $column
     * @return $this
     */
    public function orderByDesc($column)
    {

View on GitHub (pinned to e0f6eb3518)