Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🛗 fix: Add Tenant Index Upgrade Migration (#15767)

Danny Aviladad20b115e1f
diff --git a/UPGRADING.md b/UPGRADING.md
new file mode 100644
index 0000000000..51eab7cc67
--- /dev/null
+++ b/UPGRADING.md
@@ -0,0 +1,62 @@
+# Upgrading LibreChat
+
+## Tenant index migration (v0.8.7 and earlier databases)
+
+Upgrading an existing database can log `Index build failed` for User, Role,
+Preset, AccessRole, MCPServer, AgentCategory, Message, or Conversation. Older
+unique indexes (for example `email_1` or `name_1`) conflict with current non-unique
+indexes of the same name. Tenant-scoped compound indexes now enforce uniqueness.
+This also affects single-tenant deployments. See #15759 (successor to #14826).
+
+The tenant-index migration is an explicit maintenance command; startup does not
+run it automatically. Use the updated code/image containing this command. For a
+source checkout, install dependencies and build the packages first (`npm run
+build:packages`).
+
+1. Back up MongoDB and stop all LibreChat API replicas and workers that write to
+ the database. Keep MongoDB available throughout the migration.
+2. Preview known legacy unique indexes using the deployment's `MONGO_URI` and
+ connection settings from `.env`:
+
+ ```sh
+ npm run migrate:tenant-indexes:dry-run
+ ```
+
+3. Apply the migration:
+
+ ```sh
+ npm run migrate:tenant-indexes
+ ```
+
+ With Docker Compose, stop the API and run a one-off container from the updated
+ image while MongoDB remains running. Use the same Compose file flags as your
+ deployment (for example, `docker compose -f deploy-compose.yml`). Set the
+ working directory to `/app`, where the root npm scripts live; the production
+ API image otherwise defaults to `/app/api`:
+
+ ```sh
+ docker compose stop api
+ docker compose run --rm --no-deps -w /app api npm run migrate:tenant-indexes:dry-run
+ docker compose run --rm --no-deps -w /app api npm run migrate:tenant-indexes
+ docker compose up -d api
+ ```
+
+4. Restart writers only after the command exits successfully (status 0). Verify
+ that startup no longer reports these index conflicts.
+
+The command first builds tenant-scoped unique indexes, then drops only known
+superseded unique indexes, and explicitly creates current schema indexes for the
+affected collections. It preserves custom indexes and current non-unique indexes;
+it does not delete documents or use `syncIndexes`/`dropIndexes`. Automatic index
+creation is disabled in the maintenance process to prevent races, even when the
+server normally enables it. Current indexes are explicitly built even if the
+server uses `MONGO_AUTO_INDEX=false`.
+
+The dry run only lists removals: it does not validate replacement builds, database
+permissions, or duplicate data. Any listing, dropping, or building error makes
+the apply command fail. If replacement creation fails (for example due to
+existing duplicates or unsupported database index options), no old constraints
+have been dropped. Keep writers stopped, correct the reported problem, and rerun.
+A later failure can leave a partial migration; rerunning safely completes it.
+Index builds may take time on large collections. Do not drop all indexes to
+resolve a failure.
diff --git a/config/migrate-tenant-indexes.js b/config/migrate-tenant-indexes.js
new file mode 100644
index 0000000000..99ccf1ff46
--- /dev/null
+++ b/config/migrate-tenant-indexes.js
@@ -0,0 +1,21 @@
+require('dotenv').config();
+process.env.MONGO_AUTO_INDEX = 'false';
+process.env.MONGO_AUTO_CREATE = 'false';
+const mongoose = require('mongoose');
+const { migrateTenantIndexes } = require('@librechat/data-schemas');
+const connect = require('./connect');
+
+(async () => {
+ try {
+ await connect();
+ const result = await migrateTenantIndexes(mongoose.connection, {
+ dryRun: process.argv.includes('--dry-run'),
+ });
+ process.exitCode = result.errors.length > 0 ? 1 : 0;
+ } catch (error) {
+ console.error('Tenant index migration failed:', error);
+ process.exitCode = 1;
+ } finally {
+ await mongoose.disconnect();
+ }
+})();
diff --git a/package.json b/package.json
index 8812b86275..a18405175d 100644
--- a/package.json
+++ b/package.json
@@ -125,6 +125,8 @@
"b:balance": "bun config/add-balance.js",
"b:list-balances": "bun config/list-balances.js",
"reset-terms": "node config/reset-terms.js",
+ "migrate:tenant-indexes": "node config/migrate-tenant-indexes.js",
+ "migrate:tenant-indexes:dry-run": "node config/migrate-tenant-indexes.js --dry-run",
"migrate:terms-timestamp": "node config/migrate-terms-timestamp.js",
"flush-cache": "node config/flush-cache.js",
"migrate:agent-permissions:dry-run": "node config/migrate-agent-permissions.js --dry-run",
diff --git a/packages/data-schemas/src/index.ts b/packages/data-schemas/src/index.ts
index 798af371e8..0e9299b970 100644
--- a/packages/data-schemas/src/index.ts
+++ b/packages/data-schemas/src/index.ts
@@ -99,6 +99,7 @@ export {
MCPServerNameMigrationError,
createMCPAuthorityLookupIndexes,
dropSupersededTenantIndexes,
+ migrateTenantIndexes,
dropSupersededPromptGroupIndexes,
backfillMCPServerNormalizedNames,
} from './migrations';
diff --git a/packages/data-schemas/src/migrations/index.ts b/packages/data-schemas/src/migrations/index.ts
index e26cb521c7..c3ba619181 100644
--- a/packages/data-schemas/src/migrations/index.ts
+++ b/packages/data-schemas/src/migrations/index.ts
@@ -1,4 +1,4 @@
-export { dropSupersededTenantIndexes } from './tenantIndexes';
+export { dropSupersededTenantIndexes, migrateTenantIndexes } from './tenantIndexes';
export { dropSupersededPromptGroupIndexes } from './promptGroupIndexes';
export { createMCPAuthorityLookupIndexes } from './mcpAuthorityIndexes';
export { MCPServerNameMigrationError, backfillMCPServerNormalizedNames } from './mcpServerNames';
diff --git a/packages/data-schemas/src/migrations/tenantIndexes.spec.ts b/packages/data-schemas/src/migrations/tenantIndexes.spec.ts
index 986adb5ab8..48ed97a91a 100644
--- a/packages/data-schemas/src/migrations/tenantIndexes.spec.ts
+++ b/packages/data-schemas/src/migrations/tenantIndexes.spec.ts
@@ -1,6 +1,10 @@
import mongoose from 'mongoose';
import { MongoMemoryServer } from 'mongodb-memory-server';
-import { dropSupersededTenantIndexes, SUPERSEDED_INDEXES } from './tenantIndexes';
+import {
+ dropSupersededTenantIndexes,
+ migrateTenantIndexes,
+ SUPERSEDED_INDEXES,
+} from './tenantIndexes';
jest.mock('~/config/winston', () => ({
error: jest.fn(),
@@ -317,3 +321,79 @@ describe('dropSupersededTenantIndexes', () => {
});
});
});
+
+describe('operator migration', () => {
+ let instance: mongoose.Mongoose;
+
+ beforeEach(async () => {
+ instance = new mongoose.Mongoose();
+ await instance.connect(mongoServer.getUri(), {
+ dbName: 'operator',
+ autoIndex: false,
+ autoCreate: false,
+ });
+ await instance.connection.dropDatabase();
+ });
+
+ afterEach(async () => {
+ await instance.disconnect();
+ });
+
+ it('previews without changing indexes or creating collections', async () => {
+ const roles = instance.connection.db!.collection('roles');
+ await roles.createIndex({ name: 1 }, { unique: true });
+ const before = await roles.indexes();
+ const result = await migrateTenantIndexes(instance.connection, { dryRun: true });
+ expect(result.planned).toEqual(['roles.name_1']);
+ expect(result.dropped).toEqual([]);
+ expect(await roles.indexes()).toEqual(before);
+ expect(await instance.connection.db!.listCollections().toArray()).toHaveLength(1);
+ });
+
+ it('upgrades legacy indexes, preserves custom indexes, and can be rerun', async () => {
+ const roles = instance.connection.db!.collection('roles');
+ await roles.insertOne({ name: 'USER' });
+ await roles.createIndex({ name: 1 }, { unique: true });
+ await roles.createIndex({ custom: 1 }, { name: 'operator_custom' });
+ for (const [name, indexNames] of Object.entries(SUPERSEDED_INDEXES)) {
+ for (const indexName of indexNames) {
+ const fields = indexName.split('_').filter((field) => field !== '1');
+ const keys = Object.fromEntries(fields.map((field) => [field, 1 as const]));
+ await instance.connection.db!.collection(name).createIndex(keys, { unique: true });
+ }
+ }
+ const result = await migrateTenantIndexes(instance.connection);
+ expect(result.errors).toEqual([]);
+ expect(result.dropped).toHaveLength(Object.values(SUPERSEDED_INDEXES).flat().length);
+ const indexes = await roles.indexes();
+ expect(indexes.find((index) => index.name === 'name_1')?.unique).toBeUndefined();
+ expect(indexes.find((index) => index.name === 'name_1_tenantId_1')?.unique).toBe(true);
+ expect(indexes.some((index) => index.name === 'operator_custom')).toBe(true);
+ await expect(roles.insertOne({ name: 'USER' })).rejects.toThrow(/E11000/);
+ await roles.insertOne({ name: 'USER', tenantId: 'another-tenant' });
+ const rerun = await migrateTenantIndexes(instance.connection);
+ expect(rerun.errors).toEqual([]);
+ expect(rerun.dropped).toEqual([]);
+ expect(await roles.indexes()).toEqual(indexes);
+ });
+
+ it('retains legacy constraints when replacement creation fails', async () => {
+ const users = instance.connection.db!.collection('users');
+ await users.insertMany([{ email: '[email protected]' }, { email: '[email protected]' }]);
+ const roles = instance.connection.db!.collection('roles');
+ await roles.createIndex({ name: 1 }, { unique: true });
+ await expect(migrateTenantIndexes(instance.connection)).rejects.toThrow(/E11000/);
+ expect((await roles.indexes()).find((index) => index.name === 'name_1')?.unique).toBe(true);
+ });
+
+ it('reports index-listing failures instead of treating them as missing collections', async () => {
+ const roles = instance.connection.db!.collection('roles');
+ const collection = jest.spyOn(instance.connection.db!, 'collection');
+ collection.mockReturnValue(roles);
+ jest.spyOn(roles, 'indexes').mockRejectedValue(new Error('not authorized'));
+ const result = await dropSupersededTenantIndexes(instance.connection);
+ expect(result.errors).toHaveLength(Object.keys(SUPERSEDED_INDEXES).length);
+ expect(result.skipped).toEqual([]);
+ expect(result.dropped).toEqual([]);
+ });
+});
diff --git a/packages/data-schemas/src/migrations/tenantIndexes.ts b/packages/data-schemas/src/migrations/tenantIndexes.ts
index 9a84997c5c..b68a2b32d1 100644
--- a/packages/data-schemas/src/migrations/tenantIndexes.ts
+++ b/packages/data-schemas/src/migrations/tenantIndexes.ts
@@ -1,6 +1,37 @@
+import type { IndexSpecification } from 'mongodb';
import type { Connection } from 'mongoose';
+import conversationTagSchema from '~/schema/conversationTag';
+import skillSyncStatusSchema from '~/schema/skillSyncStatus';
+import agentCategorySchema from '~/schema/agentCategory';
+import { buildIndexWithRetry } from '~/utils/retry';
+import accessRoleSchema from '~/schema/accessRole';
+import mcpServerSchema from '~/schema/mcpServer';
+import messageSchema from '~/schema/message';
+import presetSchema from '~/schema/preset';
+import agentSchema from '~/schema/agent';
+import convoSchema from '~/schema/convo';
+import groupSchema from '~/schema/group';
+import userSchema from '~/schema/user';
+import roleSchema from '~/schema/role';
+import fileSchema from '~/schema/file';
import logger from '~/config/winston';
+const TENANT_SCHEMAS = {
+ users: userSchema,
+ roles: roleSchema,
+ agents: agentSchema,
+ conversations: convoSchema,
+ messages: messageSchema,
+ presets: presetSchema,
+ agentcategories: agentCategorySchema,
+ accessroles: accessRoleSchema,
+ conversationtags: conversationTagSchema,
+ mcpservers: mcpServerSchema,
+ files: fileSchema,
+ groups: groupSchema,
+ skillsyncstatuses: skillSyncStatusSchema,
+};
+
/**
* Indexes that were superseded by compound tenant-scoped indexes.
* Each entry maps a collection name to the old index names that must be dropped
@@ -39,6 +70,7 @@ const SUPERSEDED_INDEXES: Record<string, string[]> = {
};
interface MigrationResult {
+ planned: string[];
dropped: string[];
skipped: string[];
errors: string[];
@@ -53,23 +85,32 @@ interface MigrationResult {
*/
export async function dropSupersededTenantIndexes(
connection: Connection,
+ { dryRun = false }: { dryRun?: boolean } = {},
): Promise<MigrationResult> {
- const result: MigrationResult = { dropped: [], skipped: [], errors: [] };
+ const result: MigrationResult = { planned: [], dropped: [], skipped: [], errors: [] };
for (const [collectionName, indexNames] of Object.entries(SUPERSEDED_INDEXES)) {
const collection = connection.db!.collection(collectionName);
- let existingIndexes: Array<{ name?: string }>;
+ let existingIndexes: Array<{ name?: string; unique?: boolean }>;
try {
existingIndexes = await collection.indexes();
- } catch {
- result.skipped.push(
- ...indexNames.map((idx) => `${collectionName}.${idx} (collection does not exist)`),
- );
+ } catch (err) {
+ if (err instanceof Error && 'code' in err && err.code === 26) {
+ result.skipped.push(
+ ...indexNames.map((idx) => `${collectionName}.${idx} (collection does not exist)`),
+ );
+ continue;
+ }
+ const msg = `${collectionName}: ${(err as Error).message}`;
+ result.errors.push(msg);
+ logger.error(`[TenantMigration] Failed to list indexes: ${msg}`);
continue;
}
- const existingNames = new Set(existingIndexes.map((idx) => idx.name));
+ const existingNames = new Set(
+ existingIndexes.filter((idx) => idx.unique).map((idx) => idx.name),
+ );
for (const indexName of indexNames) {
if (!existingNames.has(indexName)) {
@@ -77,6 +118,12 @@ export async function dropSupersededTenantIndexes(
continue;
}
+ result.planned.push(`${collectionName}.${indexName}`);
+ if (dryRun) {
+ logger.info(`[TenantMigration] Would drop: ${collectionName}.${indexName}`);
+ continue;
+ }
+
try {
await collection.dropIndex(indexName);
result.dropped.push(`${collectionName}.${indexName}`);
@@ -89,18 +136,62 @@ export async function dropSupersededTenantIndexes(
}
}
- if (result.dropped.length > 0) {
- logger.info(
- `[TenantMigration] Migration complete. Dropped ${result.dropped.length} superseded indexes.`,
- );
- } else {
- logger.info(
- '[TenantMigration] No superseded indexes found — database is already migrated or fresh.',
- );
- }
+ logger.info(
+ `[TenantMigration] ${dryRun ? 'Dry run' : 'Index cleanup'} complete: ` +
+ `${result.planned.length} planned, ${result.dropped.length} dropped, ${result.errors.length} errors.`,
+ );
return result;
}
/** Exported for testing — the raw index map */
export { SUPERSEDED_INDEXES };
+
+/**
+ * Offline upgrade: build tenant constraints before removing global constraints,
+ * then explicitly create current indexes even when MONGO_AUTO_INDEX is disabled.
+ * The caller must connect with autoIndex and autoCreate disabled and stop writers.
+ */
+export async function migrateTenantIndexes(
+ connection: Connection,
+ { dryRun = false }: { dryRun?: boolean } = {},
+): Promise<MigrationResult> {
+ if (dryRun) {
+ return dropSupersededTenantIndexes(connection, { dryRun });
+ }
+
+ const indexes = Object.entries(TENANT_SCHEMAS).flatMap(([name, schema]) =>
+ schema.indexes().map(([keys, options]) => ({
+ collection: connection.db!.collection(name),
+ tenantScoped: 'tenantId' in keys,
+ keys: keys as IndexSpecification,
+ options: {
+ ...options,
+ unique: Boolean(options.unique),
+ },
+ })),
+ );
+ logger.info('[TenantMigration] Building tenant-scoped unique indexes before cleanup.');
+ for (const { collection, keys, options, tenantScoped } of indexes) {
+ if (options.unique && tenantScoped) {
+ await buildIndexWithRetry(
+ () => collection.createIndex(keys, options),
+ `createIndex(${collection.collectionName}.${JSON.stringify(keys)})`,
+ );
+ }
+ }
+
+ const result = await dropSupersededTenantIndexes(connection);
+ if (result.errors.length > 0) {
+ return result;
+ }
+ logger.info('[TenantMigration] Creating current schema indexes.');
+ for (const { collection, keys, options } of indexes) {
+ await buildIndexWithRetry(
+ () => collection.createIndex(keys, options),
+ `createIndex(${collection.collectionName}.${JSON.stringify(keys)})`,
+ );
+ }
+ logger.info('[TenantMigration] Migration complete.');
+ return result;
+}