open-webui/open-webui · error · HTTPException

External connection not found.

Error message

External connection not found.

What it means

Raised by POST /api/v1/knowledge/external/source/test when form_data.connection_id is truthy but _get_external_connection(form_data.connection_id) finds no stored connection. The endpoint supports two modes: reference an existing connection by id, or pass a full inline connection dict; the 404 fires only in the first mode. Note the detail string is 'External connection not found.' rather than the generic NOT_FOUND message.

Source

Thrown at backend/open_webui/routers/knowledge.py:810

        user=user,
    )
    return {
        'documents': result.get('documents', [[]])[0],
        'metadatas': result.get('metadatas', [[]])[0],
        'distances': result.get('distances', [[]])[0],
    }


@router.post('/external/source/test', response_model=dict)
async def test_external_knowledge_source(
    request: Request,
    form_data: ExternalKnowledgeSourceTestForm,
    user=Depends(get_admin_user),
):
    if form_data.connection_id:
        existing_connection = await _get_external_connection(form_data.connection_id)
        if not existing_connection:
            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail='External connection not found.')
        connection = _external_connection_update_dict(form_data.connection, existing_connection)
    else:
        connection = _external_connection_dict(form_data.connection, user.id, id='external-test')

    return await _test_external_source_definition(
        request,
        connection,
        form_data.source,
        form_data.query,
        form_data.count,
        user,
    )


@router.post('/external/connections/{id}/retrieve-test', response_model=dict)
async def test_external_knowledge_retrieval(
    request: Request,
    id: str,

View on GitHub (pinned to 01f4282f1f)

Solutions

  1. GET /knowledge/external/connections and verify the id still exists before submitting the test
  2. If the connection is gone, either recreate it or submit the full inline connection object with connection_id omitted
  3. Refresh the admin UI selection list at submit time instead of caching connection ids in long-lived state

Example fix

// before
body = { connection_id: savedConnId, source, query, count } // savedConnId deleted -> 404

// after
const conns = await (await fetch('/api/v1/knowledge/external/connections')).json();
const body = conns.some((c) => c.id === savedConnId)
  ? { connection_id: savedConnId, source, query, count }
  : { connection: inlineConnection, source, query, count };
Defensive patterns

Strategy: validation

Validate before calling

if (form.connection_id) {
  const conns = await (await fetch('/api/v1/knowledge/external/connections')).json();
  if (!conns.some((c) => c.id === form.connection_id)) {
    form = { ...form, connection_id: null, connection: inlineConnection };
  }
}
await post('/api/v1/knowledge/external/source/test', form);

Type guard

function hasLiveConnection(form: { connection_id?: string | null }, liveIds: Set<string>): boolean {
  return !form.connection_id || liveIds.has(form.connection_id);
}

Try / catch

try { await testSource(form); } catch (e) { if (e.status === 404 && /connection not found/i.test(e.detail)) reloadConnections(); else throw e; }

Prevention

When it happens

Trigger: POST /knowledge/external/source/test with a body containing connection_id of a deleted/never-existing connection. Does not fire when connection_id is null/empty (inline connection path) even if the inline dict is bad.

Common situations: Test form pre-populated with a connection id from a previous session after the admin deleted that connection; id copied between environments (dev -> prod) where the connection was never created; race where another admin deletes the connection between page load and form submit.

Related errors

AI-assisted analysis of open-webui/open-webui@01f4282f1f (2026-08-14). Data as JSON: /api/errors/6efc221046200ff2. Report an issue: GitHub.