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: Warn When interface.webSearch Blocks Native Search (#16708)

Marco Beretta46d73974b8bb
diff --git a/e2e/specs/mock/scenarios/native-search-warning.spec.ts b/e2e/specs/mock/scenarios/native-search-warning.spec.ts
new file mode 100644
index 0000000000..98119246c8
--- /dev/null
+++ b/e2e/specs/mock/scenarios/native-search-warning.spec.ts
@@ -0,0 +1,80 @@
+import { expect, test } from '@playwright/test';
+import { logger } from '@librechat/data-schemas';
+import { Permissions, PermissionTypes } from 'librechat-data-provider';
+import type { IRole, AppConfig } from '@librechat/data-schemas';
+import { updateInterfacePermissions } from '../../../../packages/api/src/app/permissions';
+
+/**
+ * Startup runs `updateInterfacePermissions` once against the stored USER and ADMIN roles.
+ * It is called here in-process with stubbed role reads and writes, so no shared role
+ * document of this run is changed while other specs are using it.
+ */
+
+const nativeSpec = { name: 'gpt-native', label: 'GPT', preset: { web_search: true } };
+const plainSpec = { name: 'plain', label: 'Plain', preset: {} };
+
+async function startupWarnings({
+ webSearch,
+ list = [nativeSpec],
+ storedUse,
+}: {
+ webSearch?: boolean;
+ list?: unknown[];
+ storedUse?: boolean;
+}): Promise<string[]> {
+ const config = { interface: webSearch === undefined ? {} : { webSearch } };
+ const appConfig = {
+ config,
+ interfaceConfig: { webSearch },
+ modelSpecs: { list },
+ } as unknown as AppConfig;
+ const getRoleByName = async (name: string) =>
+ storedUse === undefined
+ ? null
+ : ({
+ name,
+ permissions: { [PermissionTypes.WEB_SEARCH]: { [Permissions.USE]: storedUse } },
+ } as unknown as IRole);
+
+ const messages: string[] = [];
+ const original = logger.warn;
+ logger.warn = ((message: unknown) => {
+ messages.push(String(message));
+ return logger;
+ }) as typeof logger.warn;
+ try {
+ await updateInterfacePermissions({
+ appConfig,
+ getRoleByName,
+ updateAccessPermissions: async () => undefined,
+ });
+ } finally {
+ logger.warn = original;
+ }
+ return messages.filter((message) => message.includes('provider-native web search'));
+}
+
+test.describe('native web search startup warning', () => {
+ test('an operator who sets interface.webSearch false is told which native search specs it blocks @scenario:explicit-websearch-false-warns-native-search-specs', async () => {
+ const warnings = await startupWarnings({ webSearch: false });
+ expect(warnings).toHaveLength(1);
+ expect(warnings[0]).toContain('`interface.webSearch: false` denies');
+ expect(warnings[0]).toContain('gpt-native');
+ expect(warnings[0]).toContain('endpoints.agents.capabilities');
+ expect(warnings[0]).toContain('UPGRADING.md');
+ });
+
+ test('an operator who removed interface.webSearch is told the stored role still blocks native search @scenario:stored-websearch-denial-warns-when-key-unset', async () => {
+ const warnings = await startupWarnings({ storedUse: false });
+ expect(warnings).toHaveLength(1);
+ expect(warnings[0]).toContain('stored role permission keeps denying');
+ expect(warnings[0]).toContain('gpt-native');
+ });
+
+ test('startup stays silent when web search is allowed or no spec requests native search @scenario:allowed-websearch-or-no-native-specs-stays-silent', async () => {
+ expect(await startupWarnings({ webSearch: true })).toHaveLength(0);
+ expect(await startupWarnings({})).toHaveLength(0);
+ expect(await startupWarnings({ webSearch: true, storedUse: false })).toHaveLength(0);
+ expect(await startupWarnings({ webSearch: false, list: [plainSpec] })).toHaveLength(0);
+ });
+});
diff --git a/packages/api/src/app/permissions.spec.ts b/packages/api/src/app/permissions.spec.ts
index 36743d4a5d..a67e96d1d1 100644
--- a/packages/api/src/app/permissions.spec.ts
+++ b/packages/api/src/app/permissions.spec.ts
@@ -1,4 +1,4 @@
-import { loadDefaultInterface } from '@librechat/data-schemas';
+import { logger, loadDefaultInterface } from '@librechat/data-schemas';
import {
SystemRoles,
Permissions,
@@ -3062,3 +3062,69 @@ describe('updateInterfacePermissions - web search recovery', () => {
expect(grants()).toEqual([false, false]);
});
});
+
+describe('updateInterfacePermissions - native web search warning', () => {
+ const nativeSpec = { name: 'gpt-native', label: 'GPT', preset: { web_search: true } };
+
+ const run = async (webSearch: boolean | undefined, list: unknown[] = [nativeSpec]) => {
+ const config = { interface: webSearch === undefined ? {} : { webSearch } };
+ const configDefaults = { interface: {} } as TConfigDefaults;
+ const interfaceConfig = await loadDefaultInterface({ config, configDefaults });
+ const appConfig = { config, interfaceConfig, modelSpecs: { list } } as unknown as AppConfig;
+ await updateInterfacePermissions({
+ appConfig,
+ getRoleByName: mockGetRoleByName,
+ updateAccessPermissions: mockUpdateAccessPermissions,
+ });
+ };
+
+ const nativeWarnings = () =>
+ warnSpy.mock.calls.filter(([message]) =>
+ String(message).includes('provider-native web search'),
+ );
+
+ let warnSpy: jest.SpyInstance;
+
+ beforeEach(() => {
+ jest.clearAllMocks();
+ mockGetRoleByName.mockResolvedValue(null);
+ warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
+ });
+
+ afterEach(() => {
+ warnSpy.mockRestore();
+ });
+
+ it('warns when interface.webSearch: false blocks model specs that request native search', async () => {
+ await run(false);
+ const warnings = nativeWarnings();
+ expect(warnings).toHaveLength(1);
+ expect(warnings[0][0]).toContain('`interface.webSearch: false` denies');
+ expect(warnings[0][0]).toContain('gpt-native');
+ expect(warnings[0][0]).toContain('endpoints.agents.capabilities');
+ });
+
+ it('warns when the key is unset but a stored role still denies WEB_SEARCH', async () => {
+ mockGetRoleByName.mockImplementation(async (roleName: string) => ({
+ name: roleName,
+ permissions: { [PermissionTypes.WEB_SEARCH]: { [Permissions.USE]: false } },
+ }));
+ await run(undefined);
+ const warnings = nativeWarnings();
+ expect(warnings).toHaveLength(1);
+ expect(warnings[0][0]).toContain('stored role permission keeps denying');
+ expect(warnings[0][0]).toContain(SystemRoles.USER);
+ });
+
+ it('does not warn when web search is allowed or no spec requests native search', async () => {
+ await run(true);
+ await run(undefined);
+ await run(false, [{ name: 'plain', label: 'Plain', preset: {} }]);
+ mockGetRoleByName.mockImplementation(async (roleName: string) => ({
+ name: roleName,
+ permissions: { [PermissionTypes.WEB_SEARCH]: { [Permissions.USE]: false } },
+ }));
+ await run(true);
+ expect(nativeWarnings()).toHaveLength(0);
+ });
+});
diff --git a/packages/api/src/app/permissions.ts b/packages/api/src/app/permissions.ts
index c4ea6ed610..9a5960a8e7 100644
--- a/packages/api/src/app/permissions.ts
+++ b/packages/api/src/app/permissions.ts
@@ -67,6 +67,35 @@ function hasExplicitConfig(
}
}
+/**
+ * `WEB_SEARCH.USE` gates provider-native search (the `web_search` model parameter) as well as
+ * LibreChat's `web_search` tool. Warns when model specs ask for native search that a role's
+ * effective permission blocks, whether `interface.webSearch: false` sets it or a stored role keeps it.
+ */
+function warnNativeWebSearchDenied(
+ appConfig: AppConfig,
+ deniedRoles: string[],
+ isExplicitlyConfigured: boolean,
+): void {
+ if (deniedRoles.length === 0) {
+ return;
+ }
+ const specs = (appConfig.modelSpecs?.list ?? [])
+ .filter((spec) => spec.preset?.web_search === true)
+ .map((spec) => spec.name);
+ if (specs.length === 0) {
+ return;
+ }
+ const source = isExplicitlyConfigured
+ ? '`interface.webSearch: false` denies'
+ : '`interface.webSearch` is not set, and the stored role permission keeps denying';
+ logger.warn(
+ `Model specs request provider-native web search (\`preset.web_search: true\`), but ${source} the \`WEB_SEARCH\` permission for roles ${deniedRoles.join(', ')}, which also blocks native search: ${specs.join(', ')}. ` +
+ "To offer native search without LibreChat's search tool, set `interface.webSearch: true` and remove `web_search` from `endpoints.agents.capabilities`. " +
+ 'Removing `interface.webSearch` alone keeps the stored role permission; set it explicitly or update the role in the admin settings. See "Native-only web search" in UPGRADING.md.',
+ );
+}
+
export async function updateInterfacePermissions({
appConfig,
getRoleByName,
@@ -124,6 +153,7 @@ export async function updateInterfacePermissions({
};
const defaults = getConfigDefaults().interface;
+ const webSearchDeniedRoles: string[] = [];
// Permission precedence order:
// 1. Explicit user configuration (from librechat.yaml)
@@ -767,9 +797,22 @@ export async function updateInterfacePermissions({
}
}
+ const webSearchUse =
+ permissionsToUpdate[PermissionTypes.WEB_SEARCH]?.[Permissions.USE] ??
+ existingPermissions?.[PermissionTypes.WEB_SEARCH]?.[Permissions.USE];
+ if (webSearchUse === false) {
+ webSearchDeniedRoles.push(roleName);
+ }
+
// Update permissions if any need updating
if (Object.keys(permissionsToUpdate).length > 0) {
await updateAccessPermissions(roleName, permissionsToUpdate, existingRole);
}
}
+
+ warnNativeWebSearchDenied(
+ appConfig,
+ webSearchDeniedRoles,
+ hasExplicitConfig(interfaceConfig, PermissionTypes.WEB_SEARCH),
+ );
}