mongodb/laravel-mongodb · error · InvalidArgumentException

Order direction must be "asc", "desc" or a case from the…

Error message

Order direction must be "asc", "desc" or a case from the SortDirection enum.

What it means

When the direction argument of orderBy() is a string, it must be 'asc', 'ASC', 'desc' or 'DESC'. Any other string is rejected with this InvalidArgumentException rather than silently producing a wrong sort.

Solutions

1. Use 'asc'/'desc' (any case is handled for those exact words).
2. Normalize input: in_array(strtolower($dir), ['asc','desc']) or match to SortDirection before calling.
3. Pass the SortDirection enum instead of a string for type safety.

Example fix

// before
$query->orderBy('name', $request->get('dir', 'ascending'));
// after
$dir = $request->get('dir', 'asc') === 'desc' ? 'desc' : 'asc';
$query->orderBy('name', $dir);

$dir = is_string($direction) ? strtolower($direction) : $direction;
if (is_string($dir) && ! in_array($dir, ['asc', 'desc'], true)) {
    throw new InvalidArgumentException('Direction must be asc or desc');
}
$query->orderBy($column, $dir);

function normalizeSortDirection(mixed $d): string {
    return is_string($d) && in_array(strtolower($d), ['asc','desc'], true) ? strtolower($d) : 'asc';
}

try {
    $query->orderBy($column, $direction);
} catch (InvalidArgumentException $e) {
    if (str_contains($e->getMessage(), 'Order direction must be')) {
        $query->orderBy($column, 'asc');
    } else { throw $e; }
}

When it happens

Trigger: ->orderBy('created_at', 'ascending'), ->orderBy('name', 'DESC ', 'ASC', '1', '-1', or locale variants like 'aufsteigend'.

Common situations: Dynamic direction taken from request query params without normalization, or copying Eloquent/SQL styles ('ASC' is fine, but 'ascending' is not).

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unexpected SortDirection enum case.
• The stage name " " is invalid. It must start with a "$"…
• Cannot have both "id" and "_id" fields.

AI-assisted analysis of mongodb/laravel-mongodb@0634653039 (2026-09-15). Data as JSON: /api/errors/08281a7cd067f827. Report an issue: GitHub.

Appendix: source

Thrown at src/Query/Builder.php:683

    /**
     * @param SortDirection|int|string|array $direction
     *
     * @inheritdoc
     */
    #[Override]
    public function orderBy($column, $direction = 'asc')
    {
        if ($direction instanceof SortDirection) {
            $direction = match ($direction) {
                SortDirection::Ascending => 1,
                SortDirection::Descending => -1,
                default => throw new InvalidArgumentException('Unexpected SortDirection enum case.'),
            };
        } elseif (is_string($direction)) {
            $direction = match ($direction) {
                'asc', 'ASC' => 1,
                'desc', 'DESC' => -1,
                default => throw new InvalidArgumentException('Order direction must be "asc", "desc" or a case from the SortDirection enum.'),
            };
        }

        $column = (string) $column;
        if ($column === 'natural') {
            $this->orders['$natural'] = $direction;
        } else {
            $this->orders[$column] = $direction;
        }

        return $this;
    }

    /**
     * Override Illuminate's removeExistingOrdersFor to support associative order storage used by MongoDB.
     *
     * @inheritdoc
     */

View on GitHub (pinned to 0634653039)