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 Native Web Search Permission Denials (#16691)

lia-by-librechat[bot]0c5e1ce67f38
diff --git a/UPGRADING.md b/UPGRADING.md
index aecd00630c..fdeaafc82e 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -1,5 +1,47 @@
# Upgrading LibreChat
+## Native-only web search after v0.8.8-rc2
+
+Since v0.8.8-rc3 (#15875), `WEB_SEARCH.USE` authorizes both LibreChat's
+external search pipeline and provider-native search. `interface.webSearch: false`
+sets that permission to `false` for `USER` and `ADMIN`. Removing the YAML field
+preserves the stored denial; it does not restore the default grant.
+
+For native search without LibreChat's external pipeline:
+
+1. Explicitly set `interface.webSearch: true` and restart the API to restore
+ `USER` and `ADMIN` grants. This enables both roles, not just the affected user.
+ For selective access or custom roles, leave the field unset and enable
+ `WEB_SEARCH.USE` only for the intended roles in the permissions editor.
+2. Remove only `web_search` from your explicit `endpoints.agents.capabilities`
+ list, preserving the other capabilities. Omitting the list restores defaults,
+ including external search. This capability does not control native search.
+3. In each relevant model specification, keep top-level `webSearch: false` for
+ the external tool and `preset.web_search: true` for native search. Keep
+ `preset.useResponsesApi: true` for OpenAI-compatible native search.
+4. Saved agents use their own model parameters. Enable native Web Search there.
+5. Reload the client and verify the effective role permission and provider search
+ request. Responses API being enabled alone does not mean search is allowed.
+
+Example fields to merge into an existing configuration:
+
+```yaml
+interface:
+ webSearch: true # Shared role grant, including native search.
+endpoints:
+ agents:
+ # Preserve your existing list; remove only web_search.
+ capabilities: [deferred_tools, execute_code, file_search, artifacts, subagents, actions, context, skills, memory, ask_user_question, tools, chain, ocr]
+```
+
+An explicit YAML grant is reapplied on restart. After recovery, remove the field
+if the permissions editor should own future role changes. Stored grants and
+denials are preserved when the field is absent. No role reset is required.
+
+The composer palette and its pinned chips share the external capability gate in
+the updated composer. In v0.8.8, an old pinned Search badge may remain visible after
+external search is disabled; the backend still refuses to load that tool (#16673).
+
## Redis streaming now coalesces deltas by default
Redis-backed streams now batch model and tool-argument deltas in a **25 ms**
diff --git a/client/src/components/SidePanel/Agents/ModelPanel.test.tsx b/client/src/components/SidePanel/Agents/ModelPanel.test.tsx
index ddf506b4de..bb5c7a118d 100644
--- a/client/src/components/SidePanel/Agents/ModelPanel.test.tsx
+++ b/client/src/components/SidePanel/Agents/ModelPanel.test.tsx
@@ -10,10 +10,14 @@ import type { UseFormReturn } from 'react-hook-form';
import type { AgentForm } from '~/common';
import ModelPanel from './ModelPanel';
+const mockWebSearchAllowed = jest.fn(() => true);
+
const mockStartupConfig = jest.fn<Partial<TStartupConfig>, []>(() => ({}));
jest.mock('@librechat/client', () => ({
- Alert: ({ children }: { children: React.ReactNode }) => <div role="alert">{children}</div>,
+ Alert: ({ children, role = 'alert' }: React.HTMLAttributes<HTMLDivElement>) => (
+ <div role={role}>{children}</div>
+ ),
Button: ({ children, onClick, type }: React.ButtonHTMLAttributes<HTMLButtonElement>) => (
<button type={type} onClick={onClick}>
{children}
@@ -72,7 +76,7 @@ jest.mock('~/Providers', () => ({
jest.mock('~/hooks', () => ({
useLocalize: () => (key: string) => key,
- useHasAccess: () => true,
+ useHasAccess: () => mockWebSearchAllowed(),
}));
jest.mock('~/utils', () => ({
@@ -127,6 +131,61 @@ describe('ModelPanel', () => {
beforeEach(() => {
localStorage.clear();
mockStartupConfig.mockReturnValue({});
+ mockWebSearchAllowed.mockReturnValue(true);
+ });
+
+ it('explains a denied native search control without changing saved model parameters', () => {
+ mockWebSearchAllowed.mockReturnValue(false);
+ const formRef: React.MutableRefObject<UseFormReturn<AgentForm> | null> = { current: null };
+ const parameters = { web_search: true, useResponsesApi: true };
+ const { getByRole, queryByRole, rerender } = render(
+ <TestForm
+ defaultProvider={EModelEndpoint.openAI}
+ defaultModel="gpt-4o"
+ defaultModelParameters={parameters}
+ formRef={formRef}
+ models={{ [EModelEndpoint.openAI]: ['gpt-4o'] }}
+ modelsReady={true}
+ />,
+ );
+
+ expect(getByRole('status')).toHaveTextContent('com_ui_native_web_search_denied');
+ expect(formRef.current?.getValues('model_parameters')).toEqual(parameters);
+
+ mockWebSearchAllowed.mockReturnValue(true);
+ rerender(
+ <TestForm
+ defaultProvider={EModelEndpoint.openAI}
+ defaultModel="gpt-4o"
+ defaultModelParameters={parameters}
+ formRef={formRef}
+ models={{ [EModelEndpoint.openAI]: ['gpt-4o'] }}
+ modelsReady={true}
+ />,
+ );
+ expect(queryByRole('status')).toBeNull();
+ expect(formRef.current?.getValues('model_parameters')).toEqual(parameters);
+ });
+
+ it('explains why native search is unavailable even before the agent requests it', () => {
+ mockWebSearchAllowed.mockReturnValue(false);
+ const { getByRole } = render(
+ <TestForm
+ defaultProvider={EModelEndpoint.openAI}
+ defaultModel="gpt-4o"
+ models={{ [EModelEndpoint.openAI]: ['gpt-4o'] }}
+ modelsReady={true}
+ />,
+ );
+ expect(getByRole('status')).toHaveTextContent('com_ui_native_web_search_denied');
+ });
+
+ it('does not show a search warning for a provider without native search', () => {
+ mockWebSearchAllowed.mockReturnValue(false);
+ const { queryByRole } = render(
+ <TestForm defaultProvider="removed-provider" models={{}} modelsReady={true} />,
+ );
+ expect(queryByRole('status')).toBeNull();
});
it('disables model selection until the model catalogue is ready', () => {
diff --git a/client/src/components/SidePanel/Agents/ModelPanel.tsx b/client/src/components/SidePanel/Agents/ModelPanel.tsx
index a86ed63f67..8e6b480f39 100644
--- a/client/src/components/SidePanel/Agents/ModelPanel.tsx
+++ b/client/src/components/SidePanel/Agents/ModelPanel.tsx
@@ -88,6 +88,10 @@ export default function ModelPanel({
/** The rendered set omits role-gated controls; `parameterSettings.parameters`
* stays complete so the pruning effect below still recognises them. */
const { visibleParameters: parameters } = parameterSettings;
+ const webSearchBlocked =
+ !webSearchAllowed &&
+ (modelParameters?.web_search === true ||
+ parameterSettings.parameters.some((parameter) => parameter.key === 'web_search'));
/**
* Prunes `model_parameters` entries that no longer have a visible control (e.g. a
@@ -266,6 +270,11 @@ export default function ModelPanel({
)}
</div>
</div>
+ {webSearchBlocked && (
+ <Alert variant="warning" role="status">
+ {localize('com_ui_native_web_search_denied')}
+ </Alert>
+ )}
{/* Model Parameters */}
{parameters && (
<div className="h-auto max-w-full">
diff --git a/client/src/hooks/Input/__tests__/usePaletteEntries.spec.tsx b/client/src/hooks/Input/__tests__/usePaletteEntries.spec.tsx
index ce119895b4..fba0850222 100644
--- a/client/src/hooks/Input/__tests__/usePaletteEntries.spec.tsx
+++ b/client/src/hooks/Input/__tests__/usePaletteEntries.spec.tsx
@@ -204,6 +204,30 @@ describe('usePaletteEntries', () => {
expect(codeInterpreter.setIsPinned).toHaveBeenCalledWith(false);
});
+ it.each([false, true])(
+ 'withholds restored pinned search (active=%s) from both the palette and prompt bar when its capability is disabled',
+ (active) => {
+ const webSearch = toggle(active, true);
+ mockContext = { ...fullContext(), webSearch };
+ const { result, rerender } = entries();
+ expect(result.current.find((item) => item.key === 'builtin:web_search')).toEqual(
+ expect.objectContaining({ pinned: true, active }),
+ );
+
+ mockCapabilities = { ...allCapabilities, webSearchEnabled: false };
+ rerender();
+ expect(keysOf(result)).not.toContain('builtin:web_search');
+ expect(webSearch.setIsPinned).not.toHaveBeenCalled();
+ expect(webSearch.debouncedChange).not.toHaveBeenCalled();
+
+ mockCapabilities = { ...allCapabilities };
+ rerender();
+ expect(result.current.find((item) => item.key === 'builtin:web_search')).toEqual(
+ expect.objectContaining({ pinned: true, active }),
+ );
+ },
+ );
+
describe('the two gates on every tool', () => {
it.each([
[PermissionTypes.WEB_SEARCH, 'builtin:web_search'],
diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json
index e693f8998d..5ab840ff30 100644
--- a/client/src/locales/en/translation.json
+++ b/client/src/locales/en/translation.json
@@ -3194,6 +3194,7 @@
"com_ui_wakeup_task_finished": "Background task finished",
"com_ui_wakeup_tasks_finished": "{{0}} background tasks finished",
"com_ui_wakeup_view_activity": "View activity",
+ "com_ui_native_web_search_denied": "Your role does not allow web search, including provider-native search. Ask an administrator to enable your Web Search permission.",
"com_ui_web_search": "Web Search",
"com_ui_web_search_cohere_key": "Enter Cohere API Key",
"com_ui_web_search_firecrawl_url": "Firecrawl API URL (optional)",
diff --git a/librechat.example.yaml b/librechat.example.yaml
index 8c3599edc6..c01ff4eccf 100644
--- a/librechat.example.yaml
+++ b/librechat.example.yaml
@@ -775,6 +775,8 @@ endpoints:
# skills:
# maxCatalogSkills: 20
# # (optional) Agent Capabilities available to all users. Omit the ones you wish to exclude. Defaults to list below.
+ # # web_search controls only LibreChat's external pipeline, not provider-native search.
+ # # Both require WEB_SEARCH.USE, seeded by interface.webSearch. See UPGRADING.md.
# capabilities: ["deferred_tools", "execute_code", "file_search", "web_search", "artifacts", "subagents", "actions", "context", "skills", "memory", "ask_user_question", "tools", "chain", "ocr"]
# # The following capabilities are opt-in and must be added explicitly:
# # "programmatic_tools", "stateful_code_sessions", "run_in_background", "tool_intents"
diff --git a/packages/api/src/agents/__tests__/initialize.test.ts b/packages/api/src/agents/__tests__/initialize.test.ts
index 3319102e3f..50b4a05c4f 100644
--- a/packages/api/src/agents/__tests__/initialize.test.ts
+++ b/packages/api/src/agents/__tests__/initialize.test.ts
@@ -34,6 +34,7 @@ jest.mock('@librechat/agents', () => ({
import { Providers } from '@librechat/agents';
import { createHash } from 'node:crypto';
+import { logger } from '@librechat/data-schemas';
import { createRepositoryInstructionLoader } from '../../code/instructions';
import {
Tools,
@@ -5237,6 +5238,10 @@ describe('initializeAgent — authorized run file snapshots', () => {
describe('initializeAgent — provider-native web search role gate', () => {
const OPENAI_SEARCH = { type: 'web_search' };
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
const roleWithWebSearch = (use: boolean) =>
jest.fn().mockResolvedValue({
name: 'USER',
@@ -5320,6 +5325,34 @@ describe('initializeAgent — provider-native web search role gate', () => {
expect(result.tools).not.toContainEqual(OPENAI_SEARCH);
});
+ it('keeps native search when the external pipeline capability is disabled', async () => {
+ const getRoleByName = roleWithWebSearch(true);
+ const result = await run({
+ getRoleByName,
+ params: {
+ req: {
+ ...roleGatedReq(),
+ config: { endpoints: { agents: { capabilities: [AgentCapabilities.file_search] } } },
+ } as ServerRequest,
+ },
+ });
+
+ expect(result.tools).toContainEqual(OPENAI_SEARCH);
+ expect(getRoleByName).toHaveBeenCalledTimes(1);
+ expect(logger.warn).not.toHaveBeenCalledWith(expect.stringContaining('Restore the role grant'));
+ });
+
+ it('explains a blocked native request even when the caller supplies the denial', async () => {
+ const result = await run({
+ params: { resolveWebSearchGrant: jest.fn().mockResolvedValue(false) },
+ });
+
+ expect(result.tools).not.toContainEqual(OPENAI_SEARCH);
+ expect(logger.warn).toHaveBeenCalledWith(
+ expect.stringContaining('removing interface.webSearch does not reset stored permissions'),
+ );
+ });
+
it('reads no role when the built config turns no native search on', async () => {
const getRoleByName = roleWithWebSearch(false);
const resolveWebSearchGrant = jest.fn().mockResolvedValue(false);
diff --git a/packages/api/src/agents/initialize.ts b/packages/api/src/agents/initialize.ts
index 63b0f19ae8..f294c6a8f9 100644
--- a/packages/api/src/agents/initialize.ts
+++ b/packages/api/src/agents/initialize.ts
@@ -1506,9 +1506,10 @@ export async function initializeAgent(
resolve: params.resolveWebSearchGrant,
getRoleByName: db.getRoleByName,
}));
- if (webSearchDenied && stripWebSearchPlugin(llmConfig) > 0) {
- logger.debug(
- `[initializeAgent] Removed the OpenRouter web search plugin; role denies WEB_SEARCH.`,
+ if (webSearchDenied) {
+ stripWebSearchPlugin(llmConfig);
+ logger.warn(
+ '[initializeAgent] Provider-native web search was requested but blocked by WEB_SEARCH.USE. Restore the role grant explicitly; removing interface.webSearch does not reset stored permissions.',
);
}
const tokensModel =
diff --git a/packages/api/src/app/permissions.spec.ts b/packages/api/src/app/permissions.spec.ts
index f99a9d02a1..36743d4a5d 100644
--- a/packages/api/src/app/permissions.spec.ts
+++ b/packages/api/src/app/permissions.spec.ts
@@ -7,7 +7,7 @@ import {
PermissionTypes,
} from 'librechat-data-provider';
import type { TConfigDefaults, TCustomConfig } from 'librechat-data-provider';
-import type { AppConfig } from '@librechat/data-schemas';
+import type { AppConfig, IRole } from '@librechat/data-schemas';
import { updateInterfacePermissions } from './permissions';
const mockUpdateAccessPermissions = jest.fn();
@@ -3005,3 +3005,60 @@ describe('updateInterfacePermissions - permissions', () => {
}
});
});
+
+describe('updateInterfacePermissions - web search recovery', () => {
+ it('preserves a stored denial on omission and restores it only with an explicit grant', async () => {
+ const roles = new Map(
+ [SystemRoles.USER, SystemRoles.ADMIN].map((name) => [
+ name,
+ { name, permissions: { [PermissionTypes.WEB_SEARCH]: { [Permissions.USE]: true } } },
+ ]),
+ );
+ const getRoleByName = jest.fn(async (name: string) => roles.get(name as SystemRoles) as IRole);
+ const updateAccessPermissions = jest.fn<
+ ReturnType<Parameters<typeof updateInterfacePermissions>[0]['updateAccessPermissions']>,
+ Parameters<Parameters<typeof updateInterfacePermissions>[0]['updateAccessPermissions']>
+ >(async (name, updates) => {
+ const role = roles.get(name as SystemRoles);
+ const grant = updates[PermissionTypes.WEB_SEARCH]?.[Permissions.USE];
+ if (role && grant !== undefined) {
+ role.permissions[PermissionTypes.WEB_SEARCH][Permissions.USE] = grant;
+ }
+ });
+ const sync = async (webSearch?: boolean) => {
+ updateAccessPermissions.mockClear();
+ const config = { interface: webSearch === undefined ? {} : { webSearch } };
+ const interfaceConfig = await loadDefaultInterface({
+ config,
+ configDefaults: { interface: {} } as TConfigDefaults,
+ });
+ await updateInterfacePermissions({
+ appConfig: { config, interfaceConfig } as unknown as AppConfig,
+ getRoleByName,
+ updateAccessPermissions,
+ });
+ };
+ const grants = () =>
+ [...roles.values()].map(
+ (role) => role.permissions[PermissionTypes.WEB_SEARCH][Permissions.USE],
+ );
+ const expectPreserved = () => {
+ for (const [, updates] of updateAccessPermissions.mock.calls) {
+ expect(updates).not.toHaveProperty(PermissionTypes.WEB_SEARCH);
+ }
+ };
+
+ await sync(false);
+ expect(grants()).toEqual([false, false]);
+ await sync();
+ expect(grants()).toEqual([false, false]);
+ expectPreserved();
+ await sync(true);
+ expect(grants()).toEqual([true, true]);
+ await sync();
+ expect(grants()).toEqual([true, true]);
+ expectPreserved();
+ await sync(false);
+ expect(grants()).toEqual([false, false]);
+ });
+});