googleapis/mcp-toolbox · error

unable to execute query: %w

Error message

unable to execute query: %w

What it means

RunSQL executes a statement (with an optional sqlcommenter comment prepended) through the pgx pool. This error is returned when pool.Query fails — i.e. the query could not be started: syntax errors, unknown tables/columns, permission denials, or connection drops at query submission time.

Source

Thrown at internal/sources/alloydbpg/alloydb_pg.go:122

}

func (s *Source) SourceType() string {
	return SourceType
}

func (s *Source) ToConfig() sources.SourceConfig {
	return s.Config
}

func (s *Source) PostgresPool() *pgxpool.Pool {
	return s.Pool
}

func (s *Source) RunSQL(ctx context.Context, statement string, params []any) (any, error) {
	statement = sqlcommenter.PrependComment(ctx, statement, SourceType, s.SQLCommenter)
	results, err := s.Pool.Query(ctx, statement, params...)
	if err != nil {
		return nil, fmt.Errorf("unable to execute query: %w", err)
	}
	defer results.Close()

	fields := results.FieldDescriptions()
	out := []any{}
	for results.Next() {
		v, err := results.Values()
		if err != nil {
			return nil, fmt.Errorf("unable to parse row: %w", err)
		}
		row := orderedmap.Row{}
		for i, f := range fields {
			val := sources.NormalizeValue(v[i], f.DataTypeOID)
			row.Add(f.Name, val)
		}
		out = append(out, row)
	}
	// this will catch actual query execution errors

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Read the wrapped Postgres error for the exact SQLSTATE/message.
2. Run the statement manually in psql to reproduce and fix syntax/schema issues.
3. Grant the configured user the required privileges on the schema/tables.
4. Verify connection health; if connections are dropping, check network/idle timeouts.
5. For LLM-driven usage, improve tool descriptions so the model produces valid SQL against the actual schema.

-- Validate identifiers/schema before running generated SQL
SELECT table_schema, table_name FROM information_schema.tables
WHERE table_schema = 'public' AND table_name = 'my_table';
-- check grants
SELECT has_table_privilege('app_user', 'my_table', 'SELECT');

out, err := src.RunSQL(ctx, stmt, params)
if err != nil {
    var pgErr *pgconn.PgError
    if errors.As(err, &pgErr) {
        log.Printf("SQL failed: code=%s message=%s", pgErr.Code, pgErr.Message)
    }
    return fmt.Errorf("run sql failed: %w", err)
}

When it happens

Trigger: Calling RunSQL with SQL that Postgres rejects at parse/plan/start time: invalid syntax, nonexistent relation, missing SELECT permission, or a connection lost before results stream.

Common situations: LLM-generated SQL referencing wrong schema/table names, tool user lacking grants on target tables, typo in column names, or the DB connection dropped mid-session.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

• unable to parse row: %w
• unable to execute query: %w
• could not marshal operation: %w
• failed to unmarshal operation bytes: %w
• unable to create pool: %w

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/b93d19322a00ccf8. Report an issue: GitHub.