zylon-ai/private-gpt · error · ValueError

Database query tool requires at least one SQL database artif

Error message

Database query tool requires at least one SQL database artifact in the tool context.

What it means

Raised by the DatabaseQueryProcessor interceptor when a chat request includes the unresolved database query tool but the tool's context contains no SqlDatabaseArtifact. The processor refuses to resolve the tool because it has no database to bind it to.

Source

Thrown at private_gpt/components/tools/processors/database_query_processor.py:40

    def __init__(
        self,
        database_query_tool_builder: DatabaseQueryToolBuilder,
    ) -> None:
        self._builder = database_query_tool_builder

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

            tool_context = _get_tool_context(request, tool)
            sql_artifacts = [
                ctx for ctx in tool_context if isinstance(ctx, SqlDatabaseArtifact)
            ]
            if not sql_artifacts:
                raise ValueError(
                    "Database query tool requires at least one SQL database artifact in the tool context.",
                )

            chat_history = request.messages.copy()
            prompt_blocks = request.system.get_prompt()
            if prompt_blocks:
                chat_history.insert(
                    0,
                    ChatMessage(role=MessageRole.SYSTEM, blocks=prompt_blocks),
                )

            resolved = await self._builder.build_tool(
                name=tool.name or DATABASE_QUERY_TOOL_NAME,
                type=tool.type or DATABASE_QUERY_TOOL_NAME + "_v1",
                sql_artifacts=sql_artifacts,
                chat_history=chat_history,
                validate=request.tool_config.validation_mode,
                blob_visibility=request.system.blob_visibility,

View on GitHub (pinned to 4a030776a3)

Solutions

1. Attach at least one SqlDatabaseArtifact to the database query tool's context before sending the request
2. Or remove/disable the database query tool from request.tool_config.tools when no SQL database is in scope
3. Verify the artifact is attached to the same tool entry (per-tool context), not to a different tool in the same request

Example fix

# before
tools=[ToolConfig(name=DATABASE_QUERY_TOOL_NAME)]  # no context
# after
tools=[
    ToolConfig(
        name=DATABASE_QUERY_TOOL_NAME,
        context=[SqlDatabaseArtifact(dsn=..., schema=...)],
    )
]

def has_sql_artifact(tool_context) -> bool:
    return any(isinstance(ctx, SqlDatabaseArtifact) for ctx in (tool_context or []))

if not has_sql_artifact(_get_tool_context(request, tool)):
    # drop the tool or fail with a clear client-side message before sending

def is_sql_database_artifact(ctx: object) -> bool:
    return isinstance(ctx, SqlDatabaseArtifact)

try:
    await client.chat(request)
except ValueError as e:
    if "requires at least one SQL database artifact" in str(e):
        # attach SqlDatabaseArtifact and retry, or disable the tool
        raise

When it happens

Trigger: Sending a chat request with the DATABASE_QUERY_TOOL_NAME tool enabled while the tool_context for that tool is empty or only holds non-SQL artifacts (e.g. IngestedArtifact documents).

Common situations: Client enables all tools generically without attaching a database; wiring the SQL artifact under the wrong tool's context; copy-pasting a semantic-search request template and swapping only the tool name.

Related errors

• Skill management tools require a SkillArtifact in the tool c
• TOOL_NAME_CONFLICT
• mistral-common only supports function tools.
• At least one SQL database artifact 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/ead425bd104b75fa. Report an issue: GitHub.