zylon-ai/private-gpt · error · ValueError

collection is required in context

Error message

collection is required in context

What it means

ValueError from SemanticSearchToolBuilder._validate_context: a context_filter was supplied but its collection field is empty. The collection names the vector index to search, and artifacts are indexed per (collection, artifact) via VectorArtifactIndex, so an empty collection makes retrieval impossible.

Source

Thrown at private_gpt/components/tools/builders/semantic_search_builder.py:94

        prompt_builder_service: PromptBuilderService,
    ) -> None:
        self.settings = settings
        self.llm_component = llm_component
        self.vector_store_component = vector_store_component
        self.node_store_component = node_store_component
        self.embedding_component = embedding_component
        self.ingest_component = ingest_component
        self.parse_component = parse_component
        self.prompt_builder_service = prompt_builder_service

    async def _validate_context(
        self, context_filter: ContextFilter | None
    ) -> ContextFilter:
        if not context_filter:
            raise ValueError("context_filter is required")

        if not context_filter.collection:
            raise ValueError("collection is required in context")

        # If artifacts are provided, verify the related required indexes are ready
        # or throw an error
        artifacts = (
            list(set(context_filter.artifacts)) if context_filter.artifacts else None
        )
        if artifacts:
            tasks: list[Coroutine[Any, Any, None]] = []
            for artifact in artifacts:
                vector_artifact_index = VectorArtifactIndex(
                    collection=context_filter.collection,
                    artifact=artifact,
                    vector_store_component=self.vector_store_component,
                    node_store_component=self.node_store_component,
                    embedding_component=self.embedding_component,
                    ingest_component=self.ingest_component,
                    parse_component=self.parse_component,
                )

View on GitHub (pinned to 4a030776a3)

Solutions

1. Set context_filter.collection to the target collection name (commonly "default") before calling the tool.
2. Confirm the collection exists and is the one documents were ingested into, so the search hits real data.

Example fix

# before
context_filter = ContextFilter(collection="")

# after
context_filter = ContextFilter(collection="default", artifacts=[...])

if not context_filter or not context_filter.collection:
    raise ValueError("context_filter.collection must be a non-empty collection name")

def has_collection(cf) -> bool:
    return cf is not None and isinstance(getattr(cf, "collection", None), str) and bool(cf.collection.strip())

When it happens

Trigger: Calling the semantic search tool with a ContextFilter whose collection is None or empty string; validation happens after the context_filter presence check and before artifact index verification.

Common situations: Client constructs ContextFilter with only filters/artifacts and forgets collection; settings use a non-default collection name and the caller passes the default empty value; deserialization drops the field due to a schema mismatch.

Related errors

• context_filter is required
• collection is required in context
• collection is required in context
• Semantic search tool requires an ingested artifact context.
• Only one ingested context is supported.

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/f1c28a58bb0fb33c. Report an issue: GitHub.