agentscope-ai/agentscope · error · KnowledgeBaseNotFoundError

Knowledge base {knowledge_base_id!r} not found.

Error message

Knowledge base {knowledge_base_id!r} not found.

What it means

CollectionPerKbManager.get_knowledge looks up the knowledge base by (user_id, knowledge_base_id) in storage; when the record is missing it raises KnowledgeBaseNotFoundError. This is the canonical 'no such KB' signal for the KB-manager path, thrown before any embedding/credential resolution happens.

Source

Thrown at src/agentscope/app/rag/knowledge_base_manager/_collection_per_kb.py:183

                The owner user id.
            knowledge_base_id (`str`):
                The knowledge base id.

        Returns:
            `KnowledgeBase`:
                A runtime handle bound to this knowledge base.

        Raises:
            `KnowledgeBaseNotFoundError`:
                If the record does not exist or does not belong to
                the authenticated user.
        """
        record = await self._storage.get_knowledge_base(
            user_id,
            knowledge_base_id,
        )
        if record is None:
            raise KnowledgeBaseNotFoundError(
                f"Knowledge base {knowledge_base_id!r} not found.",
            )

        # KB manager is an owner-internal path: the credential lives
        # under the same owner as the knowledge base, so we read it
        # directly from storage rather than routing through the access
        # service (which is only relevant when the viewer differs from
        # the owner).
        credential_record = await self._storage.get_credential(
            record.user_id,
            record.data.embedding_model_config.credential_id,
        )
        if credential_record is None:
            raise KnowledgeBaseNotFoundError(
                f"Credential "
                f"{record.data.embedding_model_config.credential_id!r} for "
                f"knowledge base {knowledge_base_id!r} not found.",
            )

View on GitHub (pinned to e90f1c7592)

Solutions

1. Re-list knowledge bases for the user to confirm the id exists and is in scope
2. Verify you are passing the correct user_id that owns the knowledge base
3. Treat KnowledgeBaseNotFoundError as 404: clean up references/caches that hold the dead id
4. If a race is possible (delete during use), catch and retry the list-then-get flow

Example fix

# before
kb = await manager.get_knowledge(user_id, kb_id)  # KnowledgeBaseNotFoundError

# after
from agentscope.app.rag import KnowledgeBaseNotFoundError
try:
    kb = await manager.get_knowledge(user_id, kb_id)
except KnowledgeBaseNotFoundError:
    logger.warning("kb %s missing for user %s", kb_id, user_id)
    return None

kbs = await manager.list_knowledge_bases(user_id)  # or equivalent listing API
ids = {kb.knowledge_base_id for kb in kbs}
if kb_id not in ids:
    raise LookupError(f'kb {kb_id} not present for user')

null

from agentscope.app.rag import KnowledgeBaseNotFoundError
try:
    kb = await manager.get_knowledge(user_id, kb_id)
except KnowledgeBaseNotFoundError:
    kb = None  # map to HTTP 404 in your API layer

When it happens

Trigger: Calling await manager.get_knowledge(user_id, kb_id) with a kb_id that was never created, was deleted, or belongs to a different user_id (per-user isolation makes cross-user ids appear missing).

Common situations: Stale kb ids cached in client state after the KB was deleted; passing an internal id where a public/slug id is expected; multi-tenant bugs passing the wrong user_id; race where the KB is deleted between listing and fetching.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Credential {record.data.embedding_model_config.credential_id
• Session '{session_id}' not found.
• module {__name__!r} has no attribute {name!r}
• AGENTSCOPE_WORKER_BOOTSTRAP must be in 'module:attr' form, g
• DimensionPolicy: kind=ANY requires dimension=None, got dimen

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/71c821a6feb4a0f7. Report an issue: GitHub.