From fb0ca3eee79611a44e0202623dbb046e1899eac1 Mon Sep 17 00:00:00 2001
From: Danny Avila <danny@librechat.ai>
Date: Wed, 11 Mar 2026 13:17:04 -0400
Subject: [PATCH] fix: circular dependency of `~/models`

---
 api/server/controllers/assistants/helpers.js  |  2 +-
 .../middleware/assistants/validateAuthor.js   |  2 +-
 api/server/middleware/roles/index.js          | 22 ++++++++++---------
 api/server/routes/admin/auth.js               |  2 +-
 api/server/routes/files/files.js              |  2 +-
 api/server/routes/prompts.js                  |  2 +-
 api/server/routes/prompts.test.js             |  1 -
 api/server/routes/roles.js                    |  3 ++-
 8 files changed, 19 insertions(+), 17 deletions(-)

diff --git a/api/server/controllers/assistants/helpers.js b/api/server/controllers/assistants/helpers.js
index 6309268770..4630bfe7ef 100644
--- a/api/server/controllers/assistants/helpers.js
+++ b/api/server/controllers/assistants/helpers.js
@@ -8,8 +8,8 @@ const {
   initializeClient: initAzureClient,
 } = require('~/server/services/Endpoints/azureAssistants');
 const { initializeClient } = require('~/server/services/Endpoints/assistants');
+const { hasCapability } = require('~/server/middleware/roles/capabilities');
 const { getEndpointsConfig } = require('~/server/services/Config');
-const { hasCapability } = require('~/server/middleware');
 
 /**
  * @param {ServerRequest} req
diff --git a/api/server/middleware/assistants/validateAuthor.js b/api/server/middleware/assistants/validateAuthor.js
index 3be1642a71..024d6abbe3 100644
--- a/api/server/middleware/assistants/validateAuthor.js
+++ b/api/server/middleware/assistants/validateAuthor.js
@@ -1,5 +1,5 @@
 const { logger, SystemCapabilities } = require('@librechat/data-schemas');
-const { hasCapability } = require('~/server/middleware');
+const { hasCapability } = require('~/server/middleware/roles/capabilities');
 const { getAssistant } = require('~/models');
 
 /**
diff --git a/api/server/middleware/roles/index.js b/api/server/middleware/roles/index.js
index e6c315d007..f97d4b72b4 100644
--- a/api/server/middleware/roles/index.js
+++ b/api/server/middleware/roles/index.js
@@ -1,15 +1,17 @@
-const {
-  hasCapability,
-  requireCapability,
-  hasConfigCapability,
-  capabilityContextMiddleware,
-} = require('./capabilities');
+/**
+ * NOTE: hasCapability, requireCapability, hasConfigCapability, and
+ * capabilityContextMiddleware are intentionally NOT re-exported here.
+ *
+ * capabilities.js depends on ~/models, and the middleware barrel
+ * (middleware/index.js) is frequently required by modules that are
+ * themselves loaded while the barrel is still initialising — creating
+ * a circular-require that silently returns an empty exports object.
+ *
+ * Always import capability helpers directly:
+ *   require('~/server/middleware/roles/capabilities')
+ */
 const checkAdmin = require('./admin');
 
 module.exports = {
   checkAdmin,
-  hasCapability,
-  requireCapability,
-  hasConfigCapability,
-  capabilityContextMiddleware,
 };
diff --git a/api/server/routes/admin/auth.js b/api/server/routes/admin/auth.js
index e19adf54a9..530764852b 100644
--- a/api/server/routes/admin/auth.js
+++ b/api/server/routes/admin/auth.js
@@ -6,10 +6,10 @@ const { CacheKeys } = require('librechat-data-provider');
 const { SystemCapabilities } = require('@librechat/data-schemas');
 const { getAdminPanelUrl, exchangeAdminCode, createSetBalanceConfig } = require('@librechat/api');
 const { loginController } = require('~/server/controllers/auth/LoginController');
+const { requireCapability } = require('~/server/middleware/roles/capabilities');
 const { createOAuthHandler } = require('~/server/controllers/auth/oauth');
 const { findBalanceByUser, upsertBalanceFields } = require('~/models');
 const { getAppConfig } = require('~/server/services/Config');
-const { requireCapability } = require('~/server/middleware');
 const getLogStores = require('~/cache/getLogStores');
 const { getOpenIdConfig } = require('~/strategies');
 const middleware = require('~/server/middleware');
diff --git a/api/server/routes/files/files.js b/api/server/routes/files/files.js
index 3c9ed3e302..6ec69ff23b 100644
--- a/api/server/routes/files/files.js
+++ b/api/server/routes/files/files.js
@@ -24,11 +24,11 @@ const {
 const { fileAccess } = require('~/server/middleware/accessResources/fileAccess');
 const { getStrategyFunctions } = require('~/server/services/Files/strategies');
 const { getOpenAIClient } = require('~/server/controllers/assistants/helpers');
+const { hasCapability } = require('~/server/middleware/roles/capabilities');
 const { checkPermission } = require('~/server/services/PermissionService');
 const { loadAuthValues } = require('~/server/services/Tools/credentials');
 const { hasAccessToFilesViaAgent } = require('~/server/services/Files');
 const { cleanFileName } = require('~/server/utils/files');
-const { hasCapability } = require('~/server/middleware');
 const { getLogStores } = require('~/cache');
 const { Readable } = require('stream');
 const db = require('~/models');
diff --git a/api/server/routes/prompts.js b/api/server/routes/prompts.js
index c2e15ac6c0..60165d367b 100644
--- a/api/server/routes/prompts.js
+++ b/api/server/routes/prompts.js
@@ -32,7 +32,6 @@ const {
   getPrompt,
 } = require('~/models');
 const {
-  hasCapability,
   canAccessPromptGroupResource,
   canAccessPromptViaGroup,
   requireJwtAuth,
@@ -43,6 +42,7 @@ const {
   findAccessibleResources,
   grantPermission,
 } = require('~/server/services/PermissionService');
+const { hasCapability } = require('~/server/middleware/roles/capabilities');
 
 const router = express.Router();
 
diff --git a/api/server/routes/prompts.test.js b/api/server/routes/prompts.test.js
index ec162ac1fb..a3b868f022 100644
--- a/api/server/routes/prompts.test.js
+++ b/api/server/routes/prompts.test.js
@@ -36,7 +36,6 @@ jest.mock('~/models', () => {
 
 jest.mock('~/server/middleware', () => ({
   requireJwtAuth: (req, res, next) => next(),
-  hasCapability: jest.requireActual('~/server/middleware').hasCapability,
   canAccessPromptViaGroup: jest.requireActual('~/server/middleware').canAccessPromptViaGroup,
   canAccessPromptGroupResource:
     jest.requireActual('~/server/middleware').canAccessPromptGroupResource,
diff --git a/api/server/routes/roles.js b/api/server/routes/roles.js
index 1b7e4632e3..25ee47854d 100644
--- a/api/server/routes/roles.js
+++ b/api/server/routes/roles.js
@@ -12,8 +12,9 @@ const {
   peoplePickerPermissionsSchema,
   remoteAgentsPermissionsSchema,
 } = require('librechat-data-provider');
-const { hasCapability, requireCapability, requireJwtAuth } = require('~/server/middleware');
+const { hasCapability, requireCapability } = require('~/server/middleware/roles/capabilities');
 const { updateRoleByName, getRoleByName } = require('~/models');
+const { requireJwtAuth } = require('~/server/middleware');
 
 const router = express.Router();
 router.use(requireJwtAuth);