mongodb/laravel-mongodb · error · InvalidArgumentException

Unexpected SortDirection enum case.

Error message

Unexpected SortDirection enum case.

What it means

orderBy() maps the SortDirection enum to MongoDB sort ints (1/-1) with an exhaustive match; the default arm throws this InvalidArgumentException for any enum case outside Ascending/Descending. In normal usage this is unreachable, but custom/subclassed or future enum cases would trigger it.

Solutions

  1. Only pass SortDirection::Ascending or SortDirection::Descending.
  2. Use the string forms 'asc'/'desc' if unsure.
  3. After package upgrades, re-check enum usage if the SortDirection class gained new cases.

Example fix

// before
$dir = SomeOtherEnum::Both;
$query->orderBy('name', $dir);
// after
$query->orderBy('name', SortDirection::Descending);
Defensive patterns

Strategy: validation

Validate before calling

if ($direction instanceof MongoDB\Laravel\Query\SortDirection
    && ! in_array($direction, [SortDirection::Ascending, SortDirection::Descending], true)) {
    throw new InvalidArgumentException('Unsupported SortDirection case');
}
$query->orderBy($column, $direction);

Type guard

function isKnownSortDirection(mixed $d): bool {
    return $d instanceof MongoDB\Laravel\Query\SortDirection
        && in_array($d, [SortDirection::Ascending, SortDirection::Descending], true);
}

Try / catch

try {
    $query->orderBy($column, $direction);
} catch (InvalidArgumentException $e) {
    if (str_contains($e->getMessage(), 'Unexpected SortDirection enum case')) {
        $query->orderBy($column, SortDirection::Ascending);
    } else { throw $e; }
}

Prevention

When it happens

Trigger: Passing a SortDirection-like enum case that is neither SortDirection::Ascending nor SortDirection::Descending to orderBy().

Common situations: A future SortDirection case added by a library upgrade, or confusing a different library's direction enum with this package's SortDirection.

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

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

Appendix: source

Thrown at src/Query/Builder.php:677

            $this->columns = [$column];
        }

        return $this;
    }

    /**
     * @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;
    }

View on GitHub (pinned to 0634653039)