t8y2/dbx · error

sql is required

Error message

sql is required

What it means

getExplainInfo validates that the SQL text parameter is non-empty (after trimming whitespace) before doing any work, returning this error for blank input. An EXPLAIN PLAN with no statement is meaningless, so the agent fails fast with a clear validation message instead of sending an invalid request to Oracle.

Source

Thrown at agents/drivers/oracle-go/main.go:3534

	case "C":
		return "CHAR"
	default:
		return ""
	}
}

func isOracleCharacterType(dataType string) bool {
	switch dataType {
	case "CHAR", "VARCHAR2", "VARCHAR", "NCHAR", "NVARCHAR2", "RAW":
		return true
	default:
		return false
	}
}

func (s *server) getExplainInfo(sqlText, database, schema string, timeoutSecs int) (string, error) {
	if strings.TrimSpace(sqlText) == "" {
		return "", errors.New("sql is required")
	}
	db, err := s.requireDB()
	if err != nil {
		return "", err
	}

	ctx := context.Background()
	var cancel context.CancelFunc
	if timeoutSecs > 0 {
		ctx, cancel = context.WithTimeout(ctx, time.Duration(timeoutSecs)*time.Second)
	} else {
		ctx, cancel = context.WithCancel(ctx)
	}
	defer cancel()

	conn, err := db.Conn(ctx)
	if err != nil {
		return "", err

View on GitHub (pinned to c0390bff16)

Solutions

1. Pass the actual SQL statement in the sql parameter
2. Trim-validate the SQL client-side before calling and return a clearer local error
3. Fix interpolation/templating so the statement is not empty
4. Confirm the correct field name is used when building the RPC params

Example fix

// before
await driver.explain({ sql: sqlText }) // sqlText may be ""
// after
if (!sqlText || !sqlText.trim()) {
  throw new Error("explain: sql must be a non-empty statement")
}
await driver.explain({ sql: sqlText })

if (typeof sql !== 'string' || sql.trim() === '') {
  throw new Error('getExplainInfo: sql must be a non-empty statement')
}

function isValidSqlText(v) {
  return typeof v === 'string' && v.trim().length > 0
}

When it happens

Trigger: Calling the explain RPC with an empty string, a string of only spaces/tabs/newlines, or a missing/undefined sql parameter that decodes to "".

Common situations: A template/variable interpolation that produced an empty query; request builders dropping an optional field; passing the wrong variable (e.g. an empty schema) into the sql slot.

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

• Query timeout cannot be negative: " + timeoutSecs
• table read requires a SELECT query
• Agent runtime thread limits must be positive
• Databend procedure names with special characters are not sup
• Unsupported object type: null

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