Model Configuration Validation#

Overview#

RAGFlow performs client-side validation to ensure every tenant has two required system-wide defaults configured before they can use core features: an embedding model (embd_id) and a chat LLM (llm_id). When either is absent, the app surfaces a modal warning and redirects the user to the Model Providers settings page.

Validation Hook: useWarnEmptyModel#

The central piece is useWarnEmptyModel in web/src/hooks/use-warn-empty-model.tsx. It accepts four arguments:

The hook fires a useEffect that triggers the warning modal when all of these conditions hold 1:

• showEmptyModelWarn is true
• Data has finished loading (!loading)
• Either embdId or llmId is empty
• Both values are typed as string (confirming the API response arrived, not undefined)

A useRef flag (warnedRef) prevents the modal from appearing more than once per page lifecycle .

User interaction: The warning modal is non-closable (no cancel, no backdrop dismiss). Clicking OK calls navigateToModelSetting, which routes to Routes.UserSetting + Routes.Model — the Set Default Model settings page 3.

Warning message (i18n key setting.modelProvidersWarn):

"Please add both embedding model and LLM in Settings > Model providers first. Then, set them in 'Set default models'." 4

The HTML in the message is sanitized with DOMPurify before rendering 5.

Data Source: useFetchTenantInfo#

useFetchTenantInfo in web/src/hooks/use-user-setting-request.tsx fetches tenant configuration from the backend and feeds embd_id and llm_id into useWarnEmptyModel. It accepts an optional showEmptyModelWarn boolean (default false) and passes it through 6.

Note: The in-file comment at line 75 indicates this hook is being deprecated for default-model reads in favor of useFetchDefaultModelDictionary (which calls GET /api/v1/models/default). The showEmptyModelWarn path remains the canonical trigger for the empty-model check. 7

Where Validation Is Triggered#

The warning is only active where showEmptyModelWarn=true is passed. Currently this happens via useSelectParserList 8, which calls useFetchTenantInfo(true) internally. Components that invoke useSelectParserList include:

• Dataset settings — useSelectChunkMethodList in web/src/pages/dataset/dataset-setting/hooks.ts 9
• Category panel — web/src/pages/dataset/dataset-setting/category-panel.tsx 10

This means the validation fires when a user attempts to configure a Knowledge Base's chunking method — the point where both model types are first needed.

Validation Flow (Diagram)#

Component mounts (e.g. dataset-setting)
    │
    ▼
useSelectParserList()
    │
    ▼
useFetchTenantInfo(showEmptyModelWarn=true)
    │ ← GET /v1/user/info (tenant endpoint)
    ▼
useWarnEmptyModel(true, embd_id, llm_id, loading)
    │
    ├─ Both set? → No warning, normal flow
    │
    └─ Either missing (after load completes)?
           │
           ▼
       Modal.warning (non-closable)
           │
           OK button
           │
           ▼
       navigateToModelSetting()
           │
           ▼
       /user-setting/model
           (Set Default Model page)

Key Files#