zylon-ai/private-gpt · error · ValueError

At least one SQL database artifact is required.

Error message

At least one SQL database artifact is required.

What it means

ValueError raised inside the validate_sql tool closure when sql_artifacts (the list of SQL database artifacts captured at build time) is empty. The tool validates connections before running queries, and with zero artifacts there is nothing to connect to, so it refuses up front.

Source

Thrown at private_gpt/components/tools/builders/database_query_builder.py:210

        name: str = DATABASE_QUERY_TOOL_NAME,
        type: str = DATABASE_QUERY_TOOL_NAME + "_v1",
        description: str = DATABASE_QUERY_TOOL_FN.metadata.description,
        validate: ToolValidationMode = ToolValidationMode.LAZY,
        runtime: Literal["client", "server"] = "server",
        blob_visibility: BlobVisibilityMode = BlobVisibilityMode.PUBLIC,
    ) -> ToolSpec:
        (
            database_query_generator_cls,
            error_query_result_cls,
            query_result_cls,
            query_result_type_cls,
        ) = _load_database_query_dependencies()

        sample_size = self.sample_size  # capture for closure

        async def validate_sql() -> None:
            if not sql_artifacts:
                raise ValueError("At least one SQL database artifact is required.")

            query_gen = [
                database_query_generator_cls(
                    connection_string=sql_artifact.connection_string,
                    ssl=sql_artifact.ssl,
                    schemas=sql_artifact.schemas,
                    # TODO: Meanwhile we validate the feature,
                    # we set readonly to true to avoid accidental data changes
                    is_readonly=True,
                    enable_tables=sql_artifact.enable_tables,
                    enable_views=sql_artifact.enable_views,
                    enable_functions=sql_artifact.enable_functions,
                    enable_procedures=sql_artifact.enable_procedures,
                    description=sql_artifact.description,
                    batch_size=self.settings.database_query.batch_size,
                    timeout_seconds=self.settings.database_query.timeout_seconds,
                    max_mb_result=self.settings.database_query.max_mb_result,
                    cache=self.cache,

View on GitHub (pinned to 4a030776a3)

Solutions

1. Ensure the chat context includes at least one SQL database artifact with a valid connection_string before the tool runs.
2. Fix the upstream artifact resolution so sql_artifacts passed to the builder is non-empty.
3. If no database is attached for this request, do not expose/enable the database query tool in that toolset.

if not sql_artifacts:
    raise ValueError("attach at least one SQLDatabaseArtifact to the context")
# or: only expose the tool when artifacts exist
expose_db_tool = bool(sql_artifacts)

def has_sql_artifacts(context) -> bool:
    return bool(getattr(context, "sql_artifacts", None))

When it happens

Trigger: The database query tool spec is built with an empty sql_artifacts list (no SQLDatabaseArtifact in the context) and the agent then calls the validate_sql tool function.

Common situations: Chat context does not include any SQL database artifacts (user never attached a database); the artifact-filtering step upstream returned an empty list; tool was registered globally without per-request artifact wiring.

Related errors

• context_filter is required
• context_filter is required
• context_filter is required
• Database query tool requires at least one SQL database artif
• Invalid system specification (dict): {system}

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