mongodb/laravel-mongodb · error · InvalidArgumentException

The relation key of type

Error message

The relation key of type "%s" cannot be used to match aggregated values.

What it means

When hydrating grouped aggregates (HasOneOrMany withAggregate), the library matches aggregate results to parent models by stringifying the relation key (parent local key / foreign key). If that key value is neither scalar, Stringable, nor a BSON Binary (e.g. an array, DateTime, or ObjectId handled elsewhere), it cannot be converted to a comparable string key, so an InvalidArgumentException is thrown.

Solutions

1. Ensure the relation key attribute (local key / foreign key) is a scalar or Stringable value, typically an ObjectId or integer.
2. Add a model cast (e.g. 'datetime' or a custom cast implementing Stringable) so the key attribute resolves to a string.
3. Inspect the offending document and fix the stored key type in the collection.

Example fix

// before
class Order extends DocumentModel {
    protected $casts = ['group_ref' => 'array']; // used as local key
}
// after
class Order extends DocumentModel {
    protected $casts = ['group_ref' => 'string']; // scalar key usable for aggregate matching
}

// Verify the parent key attribute is scalar/Stringable before aggregating
$key = $model->getAttribute($parentKey);
if (!is_scalar($key) && !$key instanceof Stringable && !$key instanceof \MongoDB\BSON\Binary) {
    throw new InvalidArgumentException('Relation key must be scalar or Stringable.');
}

function isUsableAggregateKey(mixed $v): bool {
    return is_scalar($v) || $v instanceof Stringable || $v instanceof \MongoDB\BSON\Binary;
}

try {
    $users = User::withCount('orders')->get();
} catch (\InvalidArgumentException $e) {
    // inspect/repair documents whose relation key has an unsupported type
    logger()->error($e->getMessage());
    throw $e;
}

When it happens

Trigger: Using withCount/withSum etc. on a HasOneOrMany relation where the parent key attribute (e.g. _id or custom local key) contains a non-scalar value such as an embedded array or date object that is not Stringable, e.g. Model::withCount('items') where items' local key is an array field.

Common situations: Custom key setups: using a date, embedded document, or array as the relation key instead of an _id/scalar; documents written by other systems with unexpected key types; MongoDate/typed values not cast to string by the model's casts.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Constraints on the embedded relation
• Aggregating the hybrid relation
• is not supported for relation aggregates.
• Ordering by the aggregated field
• Parent model must be a document model.

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

Appendix: source

Thrown at src/Helpers/QueriesRelationshipAggregates.php:283

            'sum' => $values->sum($column),
            'avg' => $values->avg($column),
            'min' => $values->min($column),
            'max' => $values->max($column),
        };
    }

    /** Document keys are compared as strings, as ObjectId instances are not identical. */
    private static function aggregateKey(mixed $value): string
    {
        if ($value instanceof Binary) {
            return bin2hex($value->getData());
        }

        if (is_scalar($value) || $value instanceof Stringable) {
            return (string) $value;
        }

        throw new InvalidArgumentException(sprintf(
            'The relation key of type "%s" cannot be used to match aggregated values.',
            get_debug_type($value),
        ));
    }

    private function assertAggregateRelationSupported(Relation $relation, string $name): void
    {
        if ($relation instanceof EmbedsOneOrMany) {
            return;
        }

        if (! DocumentModel::isDocumentModel($relation->getRelated()) || $this->isAcrossConnections($relation)) {
            throw new LogicException(sprintf(
                'Aggregating the hybrid relation "%s" is not supported. The related model must be stored in MongoDB.',
                $name,
            ));
        }

View on GitHub (pinned to 0634653039)