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: Explain Tenant Index Migration on Startup Conflicts (#16176)

lia-by-librechat[bot]9efb2cb7b0cc
diff --git a/packages/data-schemas/src/migrations/tenantIndexes.ts b/packages/data-schemas/src/migrations/tenantIndexes.ts
index b68a2b32d1..bb5a8e23db 100644
--- a/packages/data-schemas/src/migrations/tenantIndexes.ts
+++ b/packages/data-schemas/src/migrations/tenantIndexes.ts
@@ -144,6 +144,27 @@ export async function dropSupersededTenantIndexes(
return result;
}
+/** Suggest the offline migration only for index conflicts in collections it covers. */
+export function getTenantIndexMigrationHint(
+ collectionName: string,
+ error: Error,
+): string | undefined {
+ if (
+ !Object.prototype.hasOwnProperty.call(SUPERSEDED_INDEXES, collectionName) ||
+ !('code' in error) ||
+ (error.code !== 85 && error.code !== 86)
+ ) {
+ return;
+ }
+
+ return (
+ 'This may be a legacy tenant-index conflict. See UPGRADING.md: back up MongoDB, ' +
+ 'stop all API replicas and other database writers, then run ' +
+ '`npm run migrate:tenant-indexes:dry-run` and `npm run migrate:tenant-indexes` ' +
+ 'from the updated application root. Keep writers stopped until the migration succeeds.'
+ );
+}
+
/** Exported for testing — the raw index map */
export { SUPERSEDED_INDEXES };
diff --git a/packages/data-schemas/src/models/index.spec.ts b/packages/data-schemas/src/models/index.spec.ts
new file mode 100644
index 0000000000..e9cf5ff07a
--- /dev/null
+++ b/packages/data-schemas/src/models/index.spec.ts
@@ -0,0 +1,88 @@
+import mongoose from 'mongoose';
+import { MongoServerError } from 'mongodb';
+import { MongoMemoryServer } from 'mongodb-memory-server';
+import { createModels } from './index';
+import logger from '~/config/winston';
+
+describe('index build diagnostics', () => {
+ const instance = new mongoose.Mongoose();
+ instance.set('autoIndex', false);
+ instance.set('autoCreate', false);
+ const models = createModels(instance);
+
+ afterEach(() => jest.restoreAllMocks());
+
+ it.each([85, 86])('explains offline migration for legacy index conflict code %i', (code) => {
+ const error = new MongoServerError({ message: 'Index options conflict', code });
+ const log = jest.spyOn(logger, 'error').mockImplementation(() => logger);
+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
+ models.Role.emit('index', error);
+ expect(log).toHaveBeenCalledWith('Index build failed for "Role": Index options conflict');
+ expect(warn).toHaveBeenCalledWith(
+ expect.stringContaining('This may be a legacy tenant-index conflict.'),
+ );
+ expect(warn).toHaveBeenCalledWith(expect.stringContaining('stop all API replicas'));
+ expect(warn).toHaveBeenCalledWith(
+ expect.stringContaining('npm run migrate:tenant-indexes:dry-run'),
+ );
+ expect(warn).toHaveBeenCalledWith(
+ expect.stringContaining('Keep writers stopped until the migration succeeds.'),
+ );
+ });
+
+ it.each([11000, 13, 67])(
+ 'does not prescribe a tenant migration for unrelated error code %i',
+ (code) => {
+ const error = new MongoServerError({ message: 'Other index failure', code });
+ const log = jest.spyOn(logger, 'error').mockImplementation(() => logger);
+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
+ models.Role.emit('index', error);
+ expect(log).toHaveBeenCalledWith('Index build failed for "Role": Other index failure');
+ expect(warn).not.toHaveBeenCalled();
+ },
+ );
+
+ it('does not suggest the migration for a collection outside its scope', () => {
+ jest.spyOn(logger, 'error').mockImplementation(() => logger);
+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
+ models.Balance.emit('index', new MongoServerError({ message: 'Index conflict', code: 85 }));
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('retains uniqueness and reports the remedy after a real legacy index conflict', async () => {
+ const server = await MongoMemoryServer.create();
+ const database = new mongoose.Mongoose();
+ database.set('autoIndex', false);
+ database.set('autoCreate', false);
+ const log = jest.spyOn(logger, 'error').mockImplementation(() => logger);
+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
+ try {
+ await database.connect(server.getUri());
+ const roles = database.connection.db!.collection('roles');
+ await roles.createIndex({ name: 1 }, { unique: true });
+ await roles.insertOne({ name: 'USER' });
+ const { Role } = createModels(database);
+ await expect(Role.createIndexes()).rejects.toThrow();
+ expect(log).toHaveBeenCalledWith(expect.stringContaining('Index build failed for "Role"'));
+ expect(warn).toHaveBeenCalledWith(expect.stringContaining('npm run migrate:tenant-indexes'));
+ const indexes = await roles.indexes();
+ expect(indexes.find((index) => index.name === 'name_1')?.unique).toBe(true);
+ expect(indexes.find((index) => index.name === 'name_1_tenantId_1')?.unique).toBe(true);
+ await expect(roles.insertOne({ name: 'USER' })).rejects.toThrow(/E11000/);
+ } finally {
+ await database.disconnect();
+ await server.stop();
+ }
+ });
+
+ it('does not attach duplicate listeners or log on a successful build', () => {
+ const before = models.Role.listenerCount('index');
+ createModels(instance);
+ expect(models.Role.listenerCount('index')).toBe(before);
+ const log = jest.spyOn(logger, 'error').mockImplementation(() => logger);
+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
+ models.Role.emit('index', null);
+ expect(log).not.toHaveBeenCalled();
+ expect(warn).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/data-schemas/src/models/index.ts b/packages/data-schemas/src/models/index.ts
index d309b04101..90c6f369d3 100644
--- a/packages/data-schemas/src/models/index.ts
+++ b/packages/data-schemas/src/models/index.ts
@@ -1,6 +1,7 @@
import { createAgentQueuedTurnModel, createAgentQueuedTurnSequenceModel } from './queuedTurn';
import { createAgentTriggerLaneSequenceModel } from './triggerLaneSequence';
import { createScheduleModel, createScheduleRunModel } from './schedule';
+import { getTenantIndexMigrationHint } from '~/migrations/tenantIndexes';
import { createSkillSyncCredentialModel } from './skillSyncCredential';
import { createOpenIDRefreshFlightModel } from './openidRefreshFlight';
import { createAgentTriggerUserPurgeModel } from './triggerUserPurge';
@@ -156,6 +157,11 @@ export function createModels(mongoose: typeof import('mongoose')): {
model.on('index', (error?: Error) => {
if (error) {
logger.error(`Index build failed for "${model.modelName}": ${error.message}`);
+ // eslint-disable-next-line no-restricted-syntax -- Collection name metadata only, no raw driver operations.
+ const hint = getTenantIndexMigrationHint(model.collection.collectionName, error);
+ if (hint) {
+ logger.warn(hint);
+ }
}
});
}