t8y2/dbx · error

SQL is required

Error message

SQL is required

What it means

getExplainInfo() runs "EXPLAIN <sql>" and requires the statement text to be non-empty after trimStatementSQL normalization. An empty EXPLAIN target is meaningless, so it throws "SQL is required" before touching the connection.

Source

Thrown at agents/drivers/hive-go/metadata.go:812

		}
		lines := make([]string, 0, len(result.Rows))
		for _, row := range result.Rows {
			if line := firstRowValue(row); line != "" {
				lines = append(lines, line)
			}
		}
		if len(lines) == 0 {
			continue
		}
		return strings.Join(lines, "\n") + "\n", nil
	}
	return "", nil
}

func (server *server) getExplainInfo(sqlText string) (string, error) {
	sqlText = trimStatementSQL(sqlText)
	if sqlText == "" {
		return "", errors.New("SQL is required")
	}
	result, err := server.executeQuery(queryOptions{SQL: "EXPLAIN " + sqlText, MaxRows: metadataQueryLimit})
	if err != nil {
		return "", err
	}
	lines := make([]string, 0, len(result.Rows))
	for _, row := range result.Rows {
		lines = append(lines, firstRowValue(row))
	}
	return strings.Join(lines, "\n"), nil
}

func (server *server) completionAssistantSearch(input completionAssistantRequest) (completionAssistantResponse, error) {
	maxResults := input.MaxResults
	if maxResults <= 0 {
		maxResults = 200
	}
	schemas := []string{firstNonEmpty(input.Schema, input.Database, server.config.Database)}

View on GitHub (pinned to c0390bff16)

Solutions

1. Pass the actual SQL statement text to getExplainInfo.
2. Check that trimStatementSQL isn't reducing your statement (e.g. pure comments) to an empty string; keep a non-comment statement body.
3. Validate SQL presence in the client before invoking the explain endpoint.
4. If explaining an empty/placeholder query intentionally, skip the explain call rather than sending it.

Example fix

// before
explain, err := getExplainInfo("-- TODO") // trims to empty -> error
// after
stmt := "SELECT * FROM sales WHERE dt = '2026-01-01'"
explain, err := getExplainInfo(stmt)

if strings.TrimSpace(sqlText) == "" {
    return "", errors.New("cannot EXPLAIN an empty statement")
}

plan, err := srv.GetExplainInfo(sqlText)
if err != nil && strings.Contains(err.Error(), "SQL is required") {
    return fmt.Errorf("explain request had no statement text")
}

When it happens

Trigger: Calling getExplainInfo / the explain dispatch path with sqlText="", whitespace, or a string that trims to empty (e.g. only comments/semicolons stripped by trimStatementSQL).

Common situations: Query-analyzer UI sending the explain request before the user typed SQL; a pipeline passing a stripped/normalized statement that ended up empty; comment-only SQL input reduced to nothing by trimming.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• table is required
• SQL is required
• Hive connection string must start with jdbc:hive2:// or hive
• token is empty
• statements are required

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/61e98ee181e5469a. Report an issue: GitHub.