{"record":{"id":"6efc221046200ff2","repo":"open-webui/open-webui","slug":"external-connection-not-found","errorCode":null,"errorMessage":"External connection not found.","messagePattern":"External connection not found\\.","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"backend/open_webui/routers/knowledge.py","lineNumber":810,"sourceCode":"        user=user,\n    )\n    return {\n        'documents': result.get('documents', [[]])[0],\n        'metadatas': result.get('metadatas', [[]])[0],\n        'distances': result.get('distances', [[]])[0],\n    }\n\n\n@router.post('/external/source/test', response_model=dict)\nasync def test_external_knowledge_source(\n    request: Request,\n    form_data: ExternalKnowledgeSourceTestForm,\n    user=Depends(get_admin_user),\n):\n    if form_data.connection_id:\n        existing_connection = await _get_external_connection(form_data.connection_id)\n        if not existing_connection:\n            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail='External connection not found.')\n        connection = _external_connection_update_dict(form_data.connection, existing_connection)\n    else:\n        connection = _external_connection_dict(form_data.connection, user.id, id='external-test')\n\n    return await _test_external_source_definition(\n        request,\n        connection,\n        form_data.source,\n        form_data.query,\n        form_data.count,\n        user,\n    )\n\n\n@router.post('/external/connections/{id}/retrieve-test', response_model=dict)\nasync def test_external_knowledge_retrieval(\n    request: Request,\n    id: str,","sourceCodeStart":792,"sourceCodeEnd":828,"githubUrl":"https://github.com/open-webui/open-webui/blob/01f4282f1ffe0d6212f58d3afbeae21fffd0c4be/backend/open_webui/routers/knowledge.py#L792-L828","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["GET /knowledge/external/connections and verify the id still exists before submitting the test","If the connection is gone, either recreate it or submit the full inline connection object with connection_id omitted","Refresh the admin UI selection list at submit time instead of caching connection ids in long-lived state"],"exampleFix":"// before\nbody = { connection_id: savedConnId, source, query, count } // savedConnId deleted -> 404\n\n// after\nconst conns = await (await fetch('/api/v1/knowledge/external/connections')).json();\nconst body = conns.some((c) => c.id === savedConnId)\n  ? { connection_id: savedConnId, source, query, count }\n  : { connection: inlineConnection, source, query, count };","handlingStrategy":"validation","validationCode":"if (form.connection_id) {\n  const conns = await (await fetch('/api/v1/knowledge/external/connections')).json();\n  if (!conns.some((c) => c.id === form.connection_id)) {\n    form = { ...form, connection_id: null, connection: inlineConnection };\n  }\n}\nawait post('/api/v1/knowledge/external/source/test', form);","typeGuard":"function hasLiveConnection(form: { connection_id?: string | null }, liveIds: Set<string>): boolean {\n  return !form.connection_id || liveIds.has(form.connection_id);\n}","tryCatchPattern":"try { await testSource(form); } catch (e) { if (e.status === 404 && /connection not found/i.test(e.detail)) reloadConnections(); else throw e; }","preventionTips":["Refresh the connection dropdown right before submitting test forms","Fall back to the inline connection mode when the referenced id disappears"],"tags":["open-webui","knowledge","external-connection","http-404","stale-reference"],"backgroundTag":null,"analyzedSha":"01f4282f1ffe0d6212f58d3afbeae21fffd0c4be","analyzedAt":"2026-08-14T18:25:22.715Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}