zylon-ai/private-gpt · error · ValueError

Semantic search tool requires an ingested artifact context.

Error message

Semantic search tool requires an ingested artifact context.

What it means

Raised by the SemanticSearchProcessor interceptor when the semantic search tool is present in a request but its tool context has no IngestedArtifact. Semantic search needs an ingested corpus (with its context_filter) to build the retrieval tool, so the request is rejected before tool resolution.

Source

Thrown at private_gpt/components/tools/processors/semantic_search_processor.py:41

        semantic_search_tool_builder: SemanticSearchToolBuilder,
    ) -> None:
        self._builder = semantic_search_tool_builder

    async def intercept(self, request: ResolvedChatRequest) -> bool:
        for tool in request.tool_config.tools:
            if not _tool_matches(
                tool, SEMANTIC_SEARCH_TOOL_NAME
            ) or not _is_unresolved_tool(tool):
                continue

            tool_context = _get_tool_context(request, tool)
            ingested_artifacts = (
                [a for a in tool_context if isinstance(a, IngestedArtifact)]
                if tool_context
                else None
            )
            if not ingested_artifacts:
                raise ValueError(
                    "Semantic search tool requires an ingested artifact context.",
                )
            if len(ingested_artifacts) > 1:
                raise ValueError("Only one ingested context is supported.")

            resolved = await self._builder.build_tool(
                model_id=request.system.model,
                name=tool.name or SEMANTIC_SEARCH_TOOL_NAME,
                type=tool.type or SEMANTIC_SEARCH_TOOL_NAME + "_v1",
                context_filter=ingested_artifacts[0].context_filter,
                generate_citations=request.citation.enabled,
                validate=request.tool_config.validation_mode,
                token_limit=request.context.maximum_context_length,
            )
            return _replace_tool(request, tool, [resolved])
        return False

View on GitHub (pinned to 4a030776a3)

Solutions

1. Attach exactly one IngestedArtifact (carrying the context_filter of the ingested corpus) to the semantic search tool's context
2. Or drop the semantic search tool from the request when no ingested corpus is in scope
3. Confirm ingestion completed and produced a context_filter before referencing it

Example fix

# before
tools=[ToolConfig(name=SEMANTIC_SEARCH_TOOL_NAME)]
# after
tools=[
    ToolConfig(
        name=SEMANTIC_SEARCH_TOOL_NAME,
        context=[IngestedArtifact(context_filter=ContextFilter(filters=...))],
    )
]

ingested = [a for a in (tool_context or []) if isinstance(a, IngestedArtifact)]
if not ingested:
    # do not include SEMANTIC_SEARCH_TOOL_NAME in the request, or attach an IngestedArtifact

def is_ingested_artifact(ctx: object) -> bool:
    return isinstance(ctx, IngestedArtifact)

try:
    resp = await client.chat(request)
except ValueError as e:
    if "requires an ingested artifact context" in str(e):
        # attach IngestedArtifact(context_filter=...) and resend
        raise

When it happens

Trigger: Enabling SEMANTIC_SEARCH_TOOL_NAME in tool_config.tools while tool_context is None/empty or contains only other artifact types (e.g. SqlDatabaseArtifact, SkillArtifact).

Common situations: Enabling 'search' tools by default in a UI without selecting a knowledge source; ingesting documents but forgetting to reference them as an IngestedArtifact in the tool context; multi-tool requests where the artifact was attached to the wrong tool.

Related errors

• Only one ingested context is supported.
• TOOL_NAME_CONFLICT
• mistral-common only supports function tools.
• context_filter is required
• collection is required in context

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