Amazon DocumentDB compatibility: $facet aggregation stage not supported

[brenwhyte]

Summary

The dashboard fails to load metrics data when backed by Amazon DocumentDB (MongoDB-compatible). All API routes that use $facet in their aggregation pipelines return error code 304: Aggregation stage not supported: '$facet'.

Environment

• innFactory librechat-admin-dashboard: latest (ghcr.io/innfactory/librechat-admin-dashboard)
• Database: Amazon DocumentDB 5.0.0 (MongoDB-compatible)
• Deployment: AWS ECS Fargate (eu-west-1)

Error

All affected API routes log:

MongoServerError: Aggregation stage not supported: '$facet'
  code: 304
  errmsg: "Aggregation stage not supported: '$facet'"

Affected routes (observed in CloudWatch logs):

• /dashboard/api/files-processed
• /dashboard/api/web-search-stats
• /dashboard/api/mcp-tool-calls
• /dashboard/api/conversations
• /dashboard/api/all-agents-stats-table
• /dashboard/api/cost-by-user
• /dashboard/api/cost-by-domain
• /dashboard/api/provider-with-model-usage
• /dashboard/api/total-request-heat-map

Root cause

Amazon DocumentDB does not implement the $facet aggregation stage, even in the 5.0 compatibility mode. See AWS DocumentDB supported MongoDB APIs.

What still works

Authentication (session/password) and the health endpoint work correctly. Only data-fetching routes using $facet fail.

Suggested fix

Replace $facet pipelines with equivalent separate queries — run each facet as an independent aggregation and merge results in application code. For example:

// Instead of:
db.collection.aggregate([{ $facet: { data: [...], total: [...] } }])

// Use two separate queries:
const [data, total] = await Promise.all([
  db.collection.aggregate([...dataStages]).toArray(),
  db.collection.aggregate([...totalStages]).toArray(),
]);

This would make the dashboard compatible with DocumentDB, Azure Cosmos DB, and other MongoDB-compatible databases that don't implement $facet.

Or at least call out in the documentation that database support if limited to MongoDB