zylon-ai/private-gpt · error · ValueError

context_filter is required

Error message

context_filter is required

What it means

ValueError from SemanticSearchToolBuilder._validate_context: the semantic search tool requires a context_filter argument, and it was passed as None or omitted. The tool has no default corpus to search, so the filter is mandatory before any retrieval happens.

Source

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

        embedding_component: EmbeddingComponent,
        ingest_component: IngestComponent,
        parse_component: ParseComponent,
        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,

View on GitHub (pinned to 4a030776a3)

Solutions

1. Pass a ContextFilter instance as context_filter when calling the semantic search tool.
2. Ensure the tool-calling layer (agent/LLM tool schema) marks context_filter as required so it is always serialized.

Example fix

# before
result = await semantic_search_tool(query="revenue 2024")

# after
from private_gpt.chat.input_models import ContextFilter
result = await semantic_search_tool(query="revenue 2024", context_filter=ContextFilter(collection="default"))

if context_filter is None:
    raise ValueError("semantic search requires context_filter")
result = await semantic_search_tool(query=q, context_filter=context_filter)

from private_gpt.chat.input_models import ContextFilter

def is_valid_context_filter(cf: ContextFilter | None) -> bool:
    return cf is not None and bool(cf.collection)

When it happens

Trigger: Invoking the semantic search tool function with context_filter=None or without the parameter; _validate_context is the first step of the tool's execution path.

Common situations: Agent/framework call omits the context argument; tool schema filled with defaults; new integration constructs the tool call payload manually and drops context_filter.

Related errors

• At least one SQL database artifact is required.
• collection is required in context
• context_filter is required
• context_filter is required
• Semantic search tool requires an ingested artifact context.

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