mongodb/laravel-mongodb · error · LogicException

is not supported for hybrid query constraints.

Error message

%s is not supported for hybrid query constraints.

What it means

Thrown by assertHybridRelationSupported when a relation type is used in addHybridHas/getRelatedConstraintKey on a hybrid (SQL+MongoDB) query that MongoDB cannot translate. Only HasOneOrMany, BelongsTo, and same-connection BelongsToMany are supported; e.g. a cross-connection BelongsToMany, HasManyThrough, or MorphToMany fires the guard. It names the unsupported relation class via class_basename().

Solutions

1. Restructure the relationship to a supported type (HasOneOrMany, BelongsTo, or a BelongsToMany within a single connection).
2. Use the whereHas-style constraint only on the connection that natively supports the relation type.
3. Fetch related records in application code instead of adding a hybrid query constraint.
4. Skip the constraint for unsupported relation types with a feature-detection check on the relation class before calling addHybridHas.

When it happens

Trigger: Thrown at src/Helpers/QueriesRelationships.php:151 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at src/Helpers/QueriesRelationships.php:151

    /**
     * @param Relation $relation
     *
     * @return void
     *
     * @throws Exception
     */
    private function assertHybridRelationSupported(Relation $relation): void
    {
        if (
            $relation instanceof HasOneOrMany
            || $relation instanceof BelongsTo
            || ($relation instanceof BelongsToMany && ! $this->isAcrossConnections($relation))
        ) {
            return;
        }

        throw new LogicException(class_basename($relation) . ' is not supported for hybrid query constraints.');
    }

    /**
     * @param Builder  $hasQuery
     * @param Relation $relation
     *
     * @return Collection
     */
    private function handleMorphToMany($hasQuery, $relation)
    {
        // First we select the parent models that have a relation to our related model,
        // Then extracts related model's ids from the pivot column
        $hasQuery->where($relation->getTable() . '.' . $relation->getMorphType(), $relation->getParent()::class);
        $relations = $hasQuery->pluck($relation->getTable());
        $relations = $relation->extractIds($relations->flatten(1)->toArray(), $relation->getForeignPivotKeyName());

        return collect($relations);
    }

View on GitHub (pinned to 0634653039)