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.

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
• Only one ingested context is supported.

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

Appendix: 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)