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: Preserve Last Good Config on Reload (#16383)

lia-by-librechat[bot]2068a8b17f31
diff --git a/api/server/services/Config/app.js b/api/server/services/Config/app.js
index ce157640fc..d67c0f0364 100644
--- a/api/server/services/Config/app.js
+++ b/api/server/services/Config/app.js
@@ -33,9 +33,9 @@ async function invalidateCodeEnvironmentConfigCache(tenantId) {
await getCodeEnvironmentRegistry().invalidateAccessibleConfigurations(tenantId);
}
-const loadBaseConfig = async () => {
+const loadBaseConfig = async (mode) => {
/** @type {TCustomConfig} */
- const config = (await loadCustomConfig()) ?? {};
+ const config = (await loadCustomConfig(true, { mode })) ?? {};
/** @type {Record<string, FunctionTool>} */
const systemTools = loadAndFormatTools({
adminFilter: config.filteredTools,
diff --git a/api/server/services/Config/loadCustomConfig.js b/api/server/services/Config/loadCustomConfig.js
index 45cec14160..c253c4f14b 100644
--- a/api/server/services/Config/loadCustomConfig.js
+++ b/api/server/services/Config/loadCustomConfig.js
@@ -1,237 +1,11 @@
const path = require('path');
-const axios = require('axios');
-const yaml = require('js-yaml');
-const keyBy = require('lodash/keyBy');
-const { loadYaml, redactConfigSecretMaps } = require('@librechat/api');
-const { Providers } = require('@librechat/agents');
-const { logger } = require('@librechat/data-schemas');
-const {
- configSchema,
- paramSettings,
- EModelEndpoint,
- EImageOutputType,
- setMaxSubagents,
- agentParamSettings,
- validateSettingDefinitions,
-} = require('librechat-data-provider');
+const { loadYaml, redactConfigSecretMaps, createCustomConfigLoader } = require('@librechat/api');
const projectRoot = path.resolve(__dirname, '..', '..', '..', '..');
const defaultConfigPath = path.resolve(projectRoot, 'librechat.yaml');
-let i = 0;
-
-const OPENROUTER_PROMPT_CACHE_DEFAULT = {
- key: 'promptCache',
- default: true,
-};
-
-function includesOpenRouter(value) {
- return typeof value === 'string' && value.toLowerCase().includes(Providers.OPENROUTER);
-}
-
-function isOpenRouterEndpoint(endpoint) {
- return includesOpenRouter(endpoint.name) || includesOpenRouter(endpoint.baseURL);
-}
-
-function shouldPreserveCustomParams(customParams) {
- const defaultEndpoint = customParams?.defaultParamsEndpoint;
- return (
- defaultEndpoint && defaultEndpoint !== 'custom' && defaultEndpoint !== Providers.OPENROUTER
- );
-}
-
-function addOpenRouterDefaults(endpoint) {
- if (!isOpenRouterEndpoint(endpoint)) {
- return;
- }
-
- if (shouldPreserveCustomParams(endpoint.customParams)) {
- return;
- }
-
- const customParams = endpoint.customParams ?? {};
- const paramDefinitions = customParams.paramDefinitions ?? [];
- const hasPromptCache = paramDefinitions.some((param) => param.key === 'promptCache');
-
- endpoint.customParams = {
- ...customParams,
- defaultParamsEndpoint: Providers.OPENROUTER,
- paramDefinitions: hasPromptCache
- ? paramDefinitions
- : [...paramDefinitions, OPENROUTER_PROMPT_CACHE_DEFAULT],
- };
-}
-
-/**
- * Load custom configuration files and caches the object if the `cache` field at root is true.
- * Validation via parsing the config file with the config schema.
- * @function loadCustomConfig
- * @returns {Promise<TCustomConfig | null>} A promise that resolves to null or the custom config object.
- * */
-async function loadCustomConfig(printConfig = true) {
- // Use CONFIG_PATH if set, otherwise fallback to defaultConfigPath
- const configPath = process.env.CONFIG_PATH || defaultConfigPath;
-
- let customConfig;
-
- if (/^https?:\/\//.test(configPath)) {
- try {
- const response = await axios.get(configPath);
- customConfig = response.data;
- } catch (error) {
- i === 0 && logger.error(`Failed to fetch the remote config file from ${configPath}`, error);
- i === 0 && i++;
- return null;
- }
- } else {
- customConfig = loadYaml(configPath);
- if (!customConfig) {
- i === 0 &&
- logger.info(
- 'Custom config file missing or YAML format invalid.\n\nCheck out the latest config file guide for configurable options and features.\nhttps://www.librechat.ai/docs/configuration/librechat_yaml\n\n',
- );
- i === 0 && i++;
- return null;
- }
-
- if (customConfig.reason || customConfig.stack) {
- i === 0 && logger.error('Config file YAML format is invalid:', customConfig);
- i === 0 && i++;
- return null;
- }
- }
-
- if (typeof customConfig === 'string') {
- try {
- customConfig = yaml.load(customConfig);
- } catch (parseError) {
- i === 0 && logger.info(`Failed to parse the YAML config from ${configPath}`, parseError);
- i === 0 && i++;
- return null;
- }
- }
-
- // Applied before parsing so specs validated in the same pass (whose subagent
- // presets share the cap) check against the configured limit. Invalid values
- // are ignored here and rejected by the schema parse below.
- setMaxSubagents(customConfig?.endpoints?.[EModelEndpoint.agents]?.maxSubagents);
-
- const result = configSchema.strict().safeParse(customConfig);
- if (result?.error?.errors?.some((err) => err?.path && err.path?.includes('imageOutputType'))) {
- throw new Error(
- `
-Please specify a correct \`imageOutputType\` value (case-sensitive).
-
- The available options are:
- - ${EImageOutputType.JPEG}
- - ${EImageOutputType.PNG}
- - ${EImageOutputType.WEBP}
-
- Refer to the latest config file guide for more information:
- https://www.librechat.ai/docs/configuration/librechat_yaml`,
- );
- }
- if (!result.success) {
- let errorMessage = `Invalid custom config file at ${configPath}:
-${JSON.stringify(result.error, null, 2)}`;
-
- logger.error(errorMessage);
- const speechError = result.error.errors.find(
- (err) =>
- err.code === 'unrecognized_keys' &&
- (err.message?.includes('stt') || err.message?.includes('tts')),
- );
-
- if (speechError) {
- logger.warn(`
-The Speech-to-text and Text-to-speech configuration format has recently changed.
-If you're getting this error, please refer to the latest documentation:
-
-https://www.librechat.ai/docs/configuration/stt_tts`);
- }
-
- if (process.env.CONFIG_BYPASS_VALIDATION === 'true') {
- logger.warn(
- 'CONFIG_BYPASS_VALIDATION is enabled. Continuing with default configuration despite validation errors.',
- );
- return null;
- }
-
- logger.error(
- 'Exiting due to invalid configuration. Set CONFIG_BYPASS_VALIDATION=true to bypass this check.',
- );
- process.exit(1);
- } else {
- if (printConfig) {
- // Masks map-valued secrets (e.g. `langfuse.headers`) so literal gateway
- // credentials are not copied into application logs on every startup.
- const loggableConfig = redactConfigSecretMaps(customConfig);
- logger.info('Custom config file loaded:');
- logger.info(JSON.stringify(loggableConfig, null, 2));
- logger.debug('Custom config:', loggableConfig);
- }
- }
-
- (customConfig.endpoints?.custom ?? []).forEach(addOpenRouterDefaults);
-
- (customConfig.endpoints?.custom ?? [])
- .filter((endpoint) => endpoint.customParams)
- .forEach((endpoint) => parseCustomParams(endpoint.name, endpoint.customParams));
-
- if (result.data.modelSpecs) {
- customConfig.modelSpecs = result.data.modelSpecs;
- }
-
- return customConfig;
-}
-
-// Validate and fill out missing values for custom parameters
-function parseCustomParams(endpointName, customParams) {
- const paramEndpoint = customParams.defaultParamsEndpoint ?? 'custom';
- customParams.defaultParamsEndpoint = paramEndpoint;
- customParams.paramDefinitions = customParams.paramDefinitions || [];
-
- // Checks if `defaultParamsEndpoint` is a key in `paramSettings`.
- const validEndpoints = new Set([
- ...Object.keys(paramSettings),
- ...Object.keys(agentParamSettings),
- ]);
- if (!validEndpoints.has(paramEndpoint)) {
- throw new Error(
- `defaultParamsEndpoint of "${endpointName}" endpoint is invalid. ` +
- `Valid options are ${Array.from(validEndpoints).join(', ')}`,
- );
- }
-
- // creates default param maps
- const regularParams = paramSettings[paramEndpoint] ?? [];
- const agentParams = agentParamSettings[paramEndpoint] ?? [];
- const defaultParams = regularParams.concat(agentParams);
- const defaultParamsMap = keyBy(defaultParams, 'key');
-
- // TODO: Remove this check once we support new parameters not part of default parameters.
- // Checks if every key in `paramDefinitions` is valid.
- const validKeys = new Set(Object.keys(defaultParamsMap));
- const paramKeys = customParams.paramDefinitions.map((param) => param.key);
- if (paramKeys.some((key) => !validKeys.has(key))) {
- throw new Error(
- `paramDefinitions of "${endpointName}" endpoint contains invalid key(s). ` +
- `Valid parameter keys are ${Array.from(validKeys).join(', ')}`,
- );
- }
-
- // Fill out missing values for custom param definitions
- customParams.paramDefinitions = customParams.paramDefinitions.map((param) => {
- return { ...defaultParamsMap[param.key], ...param, optionType: 'custom' };
- });
-
- try {
- validateSettingDefinitions(customParams.paramDefinitions);
- } catch (e) {
- throw new Error(
- `Custom parameter definitions for "${endpointName}" endpoint is malformed: ${e.message}`,
- );
- }
-}
-
-module.exports = loadCustomConfig;
+module.exports = createCustomConfigLoader({
+ loadLocal: loadYaml,
+ defaultConfigPath,
+ redactConfig: redactConfigSecretMaps,
+});
diff --git a/api/server/services/Config/loadCustomConfig.spec.js b/api/server/services/Config/loadCustomConfig.spec.js
index ca767a5600..f4e827590f 100644
--- a/api/server/services/Config/loadCustomConfig.spec.js
+++ b/api/server/services/Config/loadCustomConfig.spec.js
@@ -147,6 +147,57 @@ describe('loadCustomConfig', () => {
);
});
+ it('does not exit when config validation fails during reload', async () => {
+ process.env.CONFIG_PATH = 'invalidConfig.yaml';
+ loadYaml.mockReturnValueOnce({ invalidField: true });
+
+ await expect(loadCustomConfig(true, { mode: 'reload' })).rejects.toMatchObject({
+ name: 'ConfigReloadError',
+ validationErrors: expect.any(Array),
+ });
+ expect(mockExit).not.toHaveBeenCalled();
+ });
+
+ it('rejects a reload when the local config file is missing', async () => {
+ process.env.CONFIG_PATH = 'missingConfig.yaml';
+ loadYaml.mockReturnValueOnce(null);
+
+ await expect(loadCustomConfig(true, { mode: 'reload' })).rejects.toMatchObject({
+ name: 'ConfigReloadError',
+ });
+ expect(mockExit).not.toHaveBeenCalled();
+ });
+
+ it('rejects malformed local YAML during reload without exiting', async () => {
+ process.env.CONFIG_PATH = 'invalidConfig.yaml';
+ loadYaml.mockReturnValueOnce(new Error('Malformed YAML'));
+
+ await expect(loadCustomConfig(true, { mode: 'reload' })).rejects.toMatchObject({
+ name: 'ConfigReloadError',
+ });
+ expect(mockExit).not.toHaveBeenCalled();
+ });
+
+ it('rejects malformed remote YAML during reload without exiting', async () => {
+ process.env.CONFIG_PATH = 'https://example.com/config.yaml';
+ axios.get.mockResolvedValueOnce({ data: 'version: [unterminated' });
+
+ await expect(loadCustomConfig(true, { mode: 'reload' })).rejects.toMatchObject({
+ name: 'ConfigReloadError',
+ });
+ expect(mockExit).not.toHaveBeenCalled();
+ });
+
+ it('rejects a reload when the remote config fetch fails', async () => {
+ process.env.CONFIG_PATH = 'https://example.com/config.yaml';
+ axios.get.mockRejectedValueOnce(new Error('Network error'));
+
+ await expect(loadCustomConfig(true, { mode: 'reload' })).rejects.toMatchObject({
+ name: 'ConfigReloadError',
+ });
+ expect(mockExit).not.toHaveBeenCalled();
+ });
+
it('should handle and return null on YAML parse error for a string response from remote', async () => {
process.env.CONFIG_PATH = 'http://example.com/config.yaml';
process.env.CONFIG_BYPASS_VALIDATION = 'true';
@@ -466,6 +517,27 @@ describe('loadCustomConfig', () => {
});
});
+ it('treats an empty defaultParamsEndpoint as absent for OpenRouter', async () => {
+ const config = {
+ version: '1.0',
+ endpoints: {
+ custom: [
+ {
+ name: 'OpenRouter',
+ apiKey: 'user_provided',
+ baseURL: 'https://openrouter.ai/api/v1',
+ models: { default: ['test-model'] },
+ customParams: { defaultParamsEndpoint: '' },
+ },
+ ],
+ },
+ };
+ loadYaml.mockReturnValueOnce(config);
+
+ const loaded = await loadCustomConfig();
+ expect(loaded.endpoints.custom[0].customParams.defaultParamsEndpoint).toBe('openrouter');
+ });
+
it('preserves explicit OpenRouter promptCache defaults', async () => {
const openRouterConfig = {
version: '1.0',
diff --git a/packages/api/src/app/index.ts b/packages/api/src/app/index.ts
index bd924896eb..52e45da305 100644
--- a/packages/api/src/app/index.ts
+++ b/packages/api/src/app/index.ts
@@ -1,4 +1,5 @@
export * from './service';
+export * from './loader';
export * from './config';
export * from './metrics';
export * from './permissions';
diff --git a/packages/api/src/app/loader.ts b/packages/api/src/app/loader.ts
new file mode 100644
index 0000000000..6365450c4e
--- /dev/null
+++ b/packages/api/src/app/loader.ts
@@ -0,0 +1,331 @@
+import axios from 'axios';
+import yaml from 'js-yaml';
+import { Providers } from '@librechat/agents';
+import { logger } from '@librechat/data-schemas';
+import {
+ configSchema,
+ paramSettings,
+ EModelEndpoint,
+ EImageOutputType,
+ getMaxSubagents,
+ setMaxSubagents,
+ agentParamSettings,
+ validateSettingDefinitions,
+} from 'librechat-data-provider';
+import type { TCustomConfig, TEndpoint } from 'librechat-data-provider';
+import type { ZodIssue } from 'zod';
+
+type CustomParams = NonNullable<TEndpoint['customParams']>;
+type CustomParamDefinition = NonNullable<CustomParams['paramDefinitions']>[number];
+
+export type CustomConfigLoadMode = 'startup' | 'reload';
+
+export interface CustomConfigLoadOptions {
+ mode?: CustomConfigLoadMode;
+}
+
+export interface CustomConfigLoaderOptions {
+ defaultConfigPath: string;
+ loadLocal: (configPath: string) => unknown;
+ fetchRemote?: (configPath: string) => Promise<unknown>;
+ redactConfig: (config: TCustomConfig) => TCustomConfig;
+}
+
+export class ConfigReloadError extends Error {
+ readonly validationErrors?: readonly ZodIssue[];
+ override readonly cause?: unknown;
+
+ constructor(message: string, cause?: unknown, validationErrors?: readonly ZodIssue[]) {
+ super(message);
+ this.name = 'ConfigReloadError';
+ this.cause = cause;
+ this.validationErrors = validationErrors;
+ }
+}
+
+const OPENROUTER_PROMPT_CACHE_DEFAULT = {
+ key: 'promptCache',
+ default: true,
+};
+
+function includesOpenRouter(value: string | undefined): boolean {
+ return typeof value === 'string' && value.toLowerCase().includes(Providers.OPENROUTER);
+}
+
+function isOpenRouterEndpoint(endpoint: TEndpoint): boolean {
+ return includesOpenRouter(endpoint.name) || includesOpenRouter(endpoint.baseURL);
+}
+
+function shouldPreserveCustomParams(customParams: CustomParams | undefined): boolean {
+ const defaultEndpoint = customParams?.defaultParamsEndpoint;
+ return (
+ !!defaultEndpoint && defaultEndpoint !== 'custom' && defaultEndpoint !== Providers.OPENROUTER
+ );
+}
+
+function addOpenRouterDefaults(endpoint: TEndpoint): void {
+ if (!isOpenRouterEndpoint(endpoint) || shouldPreserveCustomParams(endpoint.customParams)) {
+ return;
+ }
+
+ const customParams: CustomParams = endpoint.customParams ?? {
+ defaultParamsEndpoint: 'custom',
+ };
+ const paramDefinitions = customParams.paramDefinitions ?? [];
+ const hasPromptCache = paramDefinitions.some((param) => param.key === 'promptCache');
+
+ endpoint.customParams = {
+ ...customParams,
+ defaultParamsEndpoint: Providers.OPENROUTER,
+ paramDefinitions: hasPromptCache
+ ? paramDefinitions
+ : [...paramDefinitions, OPENROUTER_PROMPT_CACHE_DEFAULT],
+ };
+}
+
+function getConfiguredMaxSubagents(config: unknown): number | undefined {
+ if (typeof config !== 'object' || config == null || !('endpoints' in config)) {
+ return undefined;
+ }
+ const endpoints = config.endpoints;
+ if (typeof endpoints !== 'object' || endpoints == null || !(EModelEndpoint.agents in endpoints)) {
+ return undefined;
+ }
+ const agents = endpoints[EModelEndpoint.agents];
+ if (typeof agents !== 'object' || agents == null || !('maxSubagents' in agents)) {
+ return undefined;
+ }
+ return typeof agents.maxSubagents === 'number' ? agents.maxSubagents : undefined;
+}
+
+function parseCustomParams(endpointName: string | undefined, customParams: CustomParams): void {
+ const paramEndpoint = customParams.defaultParamsEndpoint ?? 'custom';
+ customParams.defaultParamsEndpoint = paramEndpoint;
+ const paramDefinitions = customParams.paramDefinitions ?? [];
+ customParams.paramDefinitions = paramDefinitions;
+
+ const validEndpoints = new Set([
+ ...Object.keys(paramSettings),
+ ...Object.keys(agentParamSettings),
+ ]);
+ if (!validEndpoints.has(paramEndpoint)) {
+ throw new Error(
+ `defaultParamsEndpoint of "${endpointName}" endpoint is invalid. ` +
+ `Valid options are ${Array.from(validEndpoints).join(', ')}`,
+ );
+ }
+
+ const regularParams = paramSettings[paramEndpoint] ?? [];
+ const agentParams = agentParamSettings[paramEndpoint] ?? [];
+ const defaultParams = regularParams.concat(agentParams);
+ const defaultParamsMap = new Map(
+ defaultParams.map((param) => [param.key, param as CustomParamDefinition]),
+ );
+ const invalidKeys = paramDefinitions
+ .map((param) => param.key)
+ .filter((key) => !defaultParamsMap.has(key));
+ if (invalidKeys.length > 0) {
+ throw new Error(
+ `paramDefinitions of "${endpointName}" endpoint contains invalid key(s). ` +
+ `Valid parameter keys are ${Array.from(defaultParamsMap.keys()).join(', ')}`,
+ );
+ }
+
+ const parsedDefinitions = paramDefinitions.map((param) => ({
+ ...defaultParamsMap.get(param.key),
+ ...param,
+ optionType: 'custom',
+ })) as CustomParamDefinition[];
+ customParams.paramDefinitions = parsedDefinitions;
+
+ try {
+ validateSettingDefinitions(
+ parsedDefinitions as Parameters<typeof validateSettingDefinitions>[0],
+ );
+ } catch (error) {
+ const message = error instanceof Error ? error.message : String(error);
+ throw new Error(
+ `Custom parameter definitions for "${endpointName}" endpoint is malformed: ${message}`,
+ );
+ }
+}
+
+function isRemoteConfigPath(configPath: string): boolean {
+ return /^https?:\/\//.test(configPath);
+}
+
+/** Creates one process-local custom-config reader. */
+export function createCustomConfigLoader({
+ defaultConfigPath,
+ loadLocal,
+ redactConfig,
+ fetchRemote = async (configPath: string): Promise<unknown> => (await axios.get(configPath)).data,
+}: CustomConfigLoaderOptions): (
+ printConfig?: boolean,
+ options?: CustomConfigLoadOptions,
+) => Promise<TCustomConfig | null> {
+ let hasLoggedSourceFailure = false;
+
+ return async function loadCustomConfig(
+ printConfig = true,
+ options: CustomConfigLoadOptions = {},
+ ): Promise<TCustomConfig | null> {
+ const mode = options.mode ?? 'startup';
+ const configPath = process.env.CONFIG_PATH || defaultConfigPath;
+ const previousMaxSubagents = getMaxSubagents();
+ let loadedSuccessfully = false;
+
+ const failSourceLoad = (
+ message: string,
+ cause?: unknown,
+ startupLogLevel: 'error' | 'info' = 'error',
+ ): null => {
+ if (mode === 'reload') {
+ if (cause == null) {
+ logger.error(message);
+ } else {
+ logger.error(message, cause);
+ }
+ throw new ConfigReloadError(message, cause);
+ }
+ if (!hasLoggedSourceFailure) {
+ if (startupLogLevel === 'error') {
+ logger.error(message, cause);
+ } else if (cause == null) {
+ logger.info(message);
+ } else {
+ logger.info(message, cause);
+ }
+ hasLoggedSourceFailure = true;
+ }
+ return null;
+ };
+
+ try {
+ let loadedConfig: unknown;
+ if (isRemoteConfigPath(configPath)) {
+ try {
+ loadedConfig = await fetchRemote(configPath);
+ } catch (error) {
+ return failSourceLoad(`Failed to fetch the remote config file from ${configPath}`, error);
+ }
+ } else {
+ loadedConfig = loadLocal(configPath);
+ if (!loadedConfig) {
+ return failSourceLoad(
+ 'Custom config file missing or YAML format invalid.\n\n' +
+ 'Check out the latest config file guide for configurable options and features.\n' +
+ 'https://www.librechat.ai/docs/configuration/librechat_yaml\n\n',
+ undefined,
+ 'info',
+ );
+ }
+ if (
+ loadedConfig instanceof Error ||
+ (typeof loadedConfig === 'object' &&
+ loadedConfig != null &&
+ ('reason' in loadedConfig || 'stack' in loadedConfig))
+ ) {
+ return failSourceLoad('Config file YAML format is invalid:', loadedConfig);
+ }
+ }
+
+ if (typeof loadedConfig === 'string') {
+ try {
+ loadedConfig = yaml.load(loadedConfig);
+ } catch (error) {
+ return failSourceLoad(
+ `Failed to parse the YAML config from ${configPath}`,
+ error,
+ 'info',
+ );
+ }
+ }
+
+ setMaxSubagents(getConfiguredMaxSubagents(loadedConfig));
+ const result = configSchema.strict().safeParse(loadedConfig);
+ if (
+ result.error?.errors.some(
+ (error) => error.path != null && error.path.includes('imageOutputType'),
+ )
+ ) {
+ throw new Error(
+ `\nPlease specify a correct \`imageOutputType\` value (case-sensitive).\n\n` +
+ 'The available options are:\n' +
+ `- ${EImageOutputType.JPEG}\n` +
+ `- ${EImageOutputType.PNG}\n` +
+ `- ${EImageOutputType.WEBP}\n\n` +
+ 'Refer to the latest config file guide for more information:\n' +
+ 'https://www.librechat.ai/docs/configuration/librechat_yaml',
+ );
+ }
+ if (!result.success) {
+ const message = `Invalid custom config file at ${configPath}:\n${JSON.stringify(result.error, null, 2)}`;
+ logger.error(message);
+ const speechError = result.error.errors.find(
+ (error) =>
+ error.code === 'unrecognized_keys' &&
+ (error.message?.includes('stt') || error.message?.includes('tts')),
+ );
+ if (speechError) {
+ logger.warn(
+ '\nThe Speech-to-text and Text-to-speech configuration format has recently changed.\n' +
+ "If you're getting this error, please refer to the latest documentation:\n\n" +
+ 'https://www.librechat.ai/docs/configuration/stt_tts',
+ );
+ }
+
+ if (process.env.CONFIG_BYPASS_VALIDATION === 'true') {
+ logger.warn(
+ 'CONFIG_BYPASS_VALIDATION is enabled. Continuing with default configuration despite validation errors.',
+ );
+ if (mode === 'reload') {
+ throw new ConfigReloadError(message, result.error, result.error.errors);
+ }
+ return null;
+ }
+ if (mode === 'reload') {
+ throw new ConfigReloadError(message, result.error, result.error.errors);
+ }
+
+ logger.error(
+ 'Exiting due to invalid configuration. Set CONFIG_BYPASS_VALIDATION=true to bypass this check.',
+ );
+ process.exit(1);
+ }
+
+ const customConfig = loadedConfig as TCustomConfig;
+ const customEndpoints = (customConfig.endpoints?.custom ?? []) as TEndpoint[];
+ for (const endpoint of customEndpoints) {
+ addOpenRouterDefaults(endpoint);
+ }
+ for (const endpoint of customEndpoints) {
+ if (endpoint.customParams) {
+ parseCustomParams(endpoint.name, endpoint.customParams);
+ }
+ }
+ if (result.data.modelSpecs) {
+ customConfig.modelSpecs = result.data.modelSpecs;
+ }
+
+ if (printConfig) {
+ const loggableConfig = redactConfig(customConfig);
+ logger.info('Custom config file loaded:');
+ logger.info(JSON.stringify(loggableConfig, null, 2));
+ logger.debug('Custom config:', loggableConfig);
+ }
+
+ loadedSuccessfully = true;
+ return customConfig;
+ } catch (error) {
+ if (mode === 'reload' && !(error instanceof ConfigReloadError)) {
+ throw new ConfigReloadError(`Failed to reload custom config from ${configPath}`, error);
+ }
+ throw error;
+ } finally {
+ if (!loadedSuccessfully) {
+ setMaxSubagents(previousMaxSubagents);
+ }
+ }
+ };
+}
diff --git a/packages/api/src/app/service.spec.ts b/packages/api/src/app/service.spec.ts
index d8c562acf4..16f9306dae 100644
--- a/packages/api/src/app/service.spec.ts
+++ b/packages/api/src/app/service.spec.ts
@@ -1,3 +1,4 @@
+import { getMaxSubagents, setMaxSubagents } from 'librechat-data-provider';
import type { AppConfig } from '@librechat/data-schemas';
import {
createAppConfigService,
@@ -65,6 +66,7 @@ describe('createAppConfigService', () => {
const config = await getAppConfig();
expect(deps.loadBaseConfig).toHaveBeenCalledTimes(1);
+ expect(deps.loadBaseConfig).toHaveBeenCalledWith('startup');
expect(config).toEqual(deps._baseConfig);
});
@@ -103,6 +105,92 @@ describe('createAppConfigService', () => {
await getAppConfig({ refresh: true });
expect(deps.loadBaseConfig).toHaveBeenCalledTimes(2);
+ expect(deps.loadBaseConfig).toHaveBeenLastCalledWith('reload');
+ });
+
+ it.each(['invalid YAML', 'missing local file', 'remote fetch failure'])(
+ 'keeps the last good base config when reload fails: %s',
+ async (message) => {
+ const deps = createDeps();
+ const { getAppConfig, clearAppConfigCache } = createAppConfigService(deps);
+ const initial = await getAppConfig({ baseOnly: true });
+ deps.loadBaseConfig.mockRejectedValueOnce(new Error(message));
+
+ await clearAppConfigCache();
+ const reloaded = await getAppConfig({ baseOnly: true });
+
+ expect(reloaded).toBe(initial);
+ expect(deps._cache._store.get('app_config:_BASE_')).toBe(initial);
+ expect(deps.loadBaseConfig).toHaveBeenLastCalledWith('reload');
+ },
+ );
+
+ it.each(['tools', 'cache'])(
+ 'restores the subagent cap if %s publication fails',
+ async (stage) => {
+ const deps = createDeps({
+ loadBaseConfig: jest.fn().mockResolvedValue({
+ config: { endpoints: { agents: { maxSubagents: 3 } } },
+ availableTools: { previous: {} },
+ }),
+ });
+ const { getAppConfig, clearAppConfigCache } = createAppConfigService(deps);
+ try {
+ await getAppConfig({ baseOnly: true });
+ setMaxSubagents(3);
+ await clearAppConfigCache();
+ deps.loadBaseConfig.mockImplementationOnce(async () => {
+ setMaxSubagents(20);
+ return {
+ config: { endpoints: { agents: { maxSubagents: 20 } } },
+ availableTools: { new: {} },
+ };
+ });
+ if (stage === 'tools') {
+ deps.setCachedTools.mockRejectedValueOnce(new Error('tools unavailable'));
+ } else {
+ deps._cache.set.mockRejectedValueOnce(new Error('cache unavailable'));
+ }
+
+ const kept = await getAppConfig({ baseOnly: true });
+ expect(kept.config?.endpoints?.agents?.maxSubagents).toBe(3);
+ expect(getMaxSubagents()).toBe(3);
+ } finally {
+ setMaxSubagents(undefined);
+ }
+ },
+ );
+
+ it('single-flights concurrent base config reloads', async () => {
+ const deps = createDeps();
+ const { getAppConfig, clearAppConfigCache } = createAppConfigService(deps);
+ const initial = await getAppConfig({ baseOnly: true });
+ await clearAppConfigCache();
+
+ let resolveReload: ((config: AppConfig) => void) | undefined;
+ deps.loadBaseConfig.mockImplementationOnce(
+ () =>
+ new Promise<AppConfig>((resolve) => {
+ resolveReload = resolve;
+ }),
+ );
+ const reloads = Array.from({ length: 10 }, () => getAppConfig({ baseOnly: true }));
+ await Promise.resolve();
+ expect(deps.loadBaseConfig).toHaveBeenCalledTimes(2);
+
+ const next = { ...initial, interfaceConfig: { modelSelect: false } };
+ resolveReload?.(next);
+ await expect(Promise.all(reloads)).resolves.toEqual(Array(10).fill(next));
+ expect(deps.loadBaseConfig).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not convert a startup load failure into an empty config', async () => {
+ const failure = new Error('invalid startup config');
+ const deps = createDeps({ loadBaseConfig: jest.fn().mockRejectedValue(failure) });
+ const { getAppConfig } = createAppConfigService(deps);
+
+ await expect(getAppConfig({ baseOnly: true })).rejects.toBe(failure);
+ expect(deps.loadBaseConfig).toHaveBeenCalledWith('startup');
});
it('queries DB for applicable configs', async () => {
diff --git a/packages/api/src/app/service.ts b/packages/api/src/app/service.ts
index 4d1c2173d2..ebc4da01f9 100644
--- a/packages/api/src/app/service.ts
+++ b/packages/api/src/app/service.ts
@@ -1,4 +1,8 @@
-import { PrincipalType, materializeModelSpecEndpoints } from 'librechat-data-provider';
+import {
+ PrincipalType,
+ materializeModelSpecEndpoints,
+ setMaxSubagents,
+} from 'librechat-data-provider';
import {
logger,
getTenantId,
@@ -7,6 +11,7 @@ import {
} from '@librechat/data-schemas';
import type { AppConfig, IConfig } from '@librechat/data-schemas';
import type { Types } from 'mongoose';
+import type { CustomConfigLoadMode } from './loader';
const BASE_CONFIG_KEY = '_BASE_';
@@ -47,7 +52,7 @@ interface CacheStore {
export interface AppConfigServiceDeps {
/** Load the base AppConfig from YAML + AppService processing. */
- loadBaseConfig: () => Promise<AppConfig | undefined>;
+ loadBaseConfig: (mode?: CustomConfigLoadMode) => Promise<AppConfig | undefined>;
/** Cache tools after base config is loaded. */
setCachedTools: (tools: Record<string, unknown>) => Promise<void>;
/** Get a cache store by key. */
@@ -163,6 +168,8 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {
} = deps;
const cache = getCache(cacheKeys.APP_CONFIG);
+ let lastGoodBaseConfig: AppConfig | undefined;
+ let baseConfigFlight: Promise<AppConfig> | undefined;
async function buildPrincipals(
role?: string,
@@ -186,29 +193,80 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {
return principals;
}
+ async function restoreLastGoodBaseConfig(error: unknown): Promise<AppConfig> {
+ const lastGood = lastGoodBaseConfig;
+ if (!lastGood) {
+ throw error;
+ }
+
+ setMaxSubagents(lastGood.config?.endpoints?.agents?.maxSubagents);
+ logger.error(
+ '[ensureBaseConfig] Failed to reload base configuration; keeping the last good configuration.',
+ error,
+ );
+ const restorations = [cache.set(BASE_CONFIG_KEY, lastGood)];
+ if (lastGood.availableTools) {
+ restorations.push(setCachedTools(lastGood.availableTools));
+ }
+ const results = await Promise.allSettled(restorations);
+ for (const result of results) {
+ if (result.status === 'rejected') {
+ logger.error('[ensureBaseConfig] Failed to restore last-good config state:', result.reason);
+ }
+ }
+ return lastGood;
+ }
+
+ async function loadAndCacheBaseConfig(mode: CustomConfigLoadMode): Promise<AppConfig> {
+ try {
+ logger.info('[ensureBaseConfig] Loading base configuration...');
+ const loaded = await loadBaseConfig(mode);
+ if (!loaded) {
+ throw new Error('Failed to initialize app configuration through AppService.');
+ }
+
+ const baseConfig = materializeConfigModelSpecs(loaded);
+ if (baseConfig.availableTools) {
+ await setCachedTools(baseConfig.availableTools);
+ }
+ await cache.set(BASE_CONFIG_KEY, baseConfig);
+ lastGoodBaseConfig = baseConfig;
+ return baseConfig;
+ } catch (error) {
+ if (mode === 'startup') {
+ throw error;
+ }
+ return restoreLastGoodBaseConfig(error);
+ }
+ }
+
/**
* Ensure the YAML-derived base config is loaded and cached.
* Returns the `_BASE_` config (YAML + AppService). No DB queries.
*/
async function ensureBaseConfig(refresh?: boolean): Promise<AppConfig> {
- let baseConfig = (await cache.get(BASE_CONFIG_KEY)) as AppConfig | undefined;
- if (!baseConfig || refresh) {
- logger.info('[ensureBaseConfig] Loading base configuration...');
- baseConfig = await loadBaseConfig();
-
- if (!baseConfig) {
- throw new Error('Failed to initialize app configuration through AppService.');
+ const cached = (await cache.get(BASE_CONFIG_KEY)) as AppConfig | undefined;
+ if (cached) {
+ lastGoodBaseConfig ??= cached;
+ if (!refresh) {
+ return cached;
}
+ }
- baseConfig = materializeConfigModelSpecs(baseConfig);
+ if (baseConfigFlight) {
+ return baseConfigFlight;
+ }
- if (baseConfig.availableTools) {
- await setCachedTools(baseConfig.availableTools);
+ const mode: CustomConfigLoadMode = lastGoodBaseConfig ? 'reload' : 'startup';
+ const flight = loadAndCacheBaseConfig(mode);
+ baseConfigFlight = flight;
+ try {
+ return await flight;
+ } finally {
+ if (baseConfigFlight === flight) {
+ baseConfigFlight = undefined;
}
-
- await cache.set(BASE_CONFIG_KEY, baseConfig);
}
- return baseConfig;
}
/**