{"record":{"id":"ead425bd104b75fa","repo":"zylon-ai/private-gpt","slug":"database-query-tool-requires-at-least-one-sql-data","errorCode":null,"errorMessage":"Database query tool requires at least one SQL database artifact in the tool context.","messagePattern":"Database query tool requires at least one SQL database artifact in the tool context\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"private_gpt/components/tools/processors/database_query_processor.py","lineNumber":40,"sourceCode":"    def __init__(\n        self,\n        database_query_tool_builder: DatabaseQueryToolBuilder,\n    ) -> None:\n        self._builder = database_query_tool_builder\n\n    async def intercept(self, request: ResolvedChatRequest) -> bool:\n        for tool in request.tool_config.tools:\n            if not _tool_matches(\n                tool, DATABASE_QUERY_TOOL_NAME\n            ) or not _is_unresolved_tool(tool):\n                continue\n\n            tool_context = _get_tool_context(request, tool)\n            sql_artifacts = [\n                ctx for ctx in tool_context if isinstance(ctx, SqlDatabaseArtifact)\n            ]\n            if not sql_artifacts:\n                raise ValueError(\n                    \"Database query tool requires at least one SQL database artifact in the tool context.\",\n                )\n\n            chat_history = request.messages.copy()\n            prompt_blocks = request.system.get_prompt()\n            if prompt_blocks:\n                chat_history.insert(\n                    0,\n                    ChatMessage(role=MessageRole.SYSTEM, blocks=prompt_blocks),\n                )\n\n            resolved = await self._builder.build_tool(\n                name=tool.name or DATABASE_QUERY_TOOL_NAME,\n                type=tool.type or DATABASE_QUERY_TOOL_NAME + \"_v1\",\n                sql_artifacts=sql_artifacts,\n                chat_history=chat_history,\n                validate=request.tool_config.validation_mode,\n                blob_visibility=request.system.blob_visibility,","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/zylon-ai/private-gpt/blob/4a030776a31a901ad80b1bf4d7faa2c1a367efbb/private_gpt/components/tools/processors/database_query_processor.py#L22-L58","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Attach at least one SqlDatabaseArtifact to the database query tool's context before sending the request","Or remove/disable the database query tool from request.tool_config.tools when no SQL database is in scope","Verify the artifact is attached to the same tool entry (per-tool context), not to a different tool in the same request"],"exampleFix":"# before\ntools=[ToolConfig(name=DATABASE_QUERY_TOOL_NAME)]  # no context\n# after\ntools=[\n    ToolConfig(\n        name=DATABASE_QUERY_TOOL_NAME,\n        context=[SqlDatabaseArtifact(dsn=..., schema=...)],\n    )\n]","handlingStrategy":"validation","validationCode":"def has_sql_artifact(tool_context) -> bool:\n    return any(isinstance(ctx, SqlDatabaseArtifact) for ctx in (tool_context or []))\n\nif not has_sql_artifact(_get_tool_context(request, tool)):\n    # drop the tool or fail with a clear client-side message before sending","typeGuard":"def is_sql_database_artifact(ctx: object) -> bool:\n    return isinstance(ctx, SqlDatabaseArtifact)","tryCatchPattern":"try:\n    await client.chat(request)\nexcept ValueError as e:\n    if \"requires at least one SQL database artifact\" in str(e):\n        # attach SqlDatabaseArtifact and retry, or disable the tool\n        raise","preventionTips":["Build tool configs from templates that pair each tool with its required artifact type","Client-side: assert every context-requiring tool has at least one matching artifact before submit","Log which tool triggered the rejection to speed up request fixes"],"tags":["tools","validation","database","request-validation"],"backgroundTag":null,"analyzedSha":"4a030776a31a901ad80b1bf4d7faa2c1a367efbb","analyzedAt":"2026-08-15T03:51:26.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}