table name is ambiguous: %s.%s; specify the catalog's exact

Error message

table name is ambiguous: %s.%s; specify the catalog's exact case

What it means

When table resolution finds multiple case-insensitive candidates for schema.table, the driver cannot disambiguate and throws this error, asking for the catalog's exact case. This protects against generating DDL for the wrong object.

Source

Thrown at agents/drivers/xugu/main.go:3848

	if err := rows.Err(); err != nil {
		return nil, err
	}
	return candidates, nil
}

func selectXuguCatalogTableName(schema, table string, candidates []xuguCatalogTableName) (string, string, error) {
	for _, candidate := range candidates {
		if candidate.Schema == schema && candidate.Table == table {
			return candidate.Schema, candidate.Table, nil
		}
	}
	if len(candidates) == 1 {
		return candidates[0].Schema, candidates[0].Table, nil
	}
	if len(candidates) == 0 {
		return "", "", fmt.Errorf("table not found: %s.%s", schema, table)
	}
	return "", "", fmt.Errorf("table name is ambiguous: %s.%s; specify the catalog's exact case", schema, table)
}

func (s *server) getExplainInfo(sqlText string) (string, error) {
	if strings.TrimSpace(sqlText) == "" {
		return "", errors.New("sql is required")
	}
	rows, err := s.queryRowsWithTimeoutOnce("EXPLAIN "+trimStatementSQL(sqlText), nil, 0)
	if err != nil {
		return "", err
	}
	defer s.closeRows(rows)
	columns, err := rows.Columns()
	if err != nil {
		return "", err
	}
	var builder strings.Builder
	for rows.Next() {
		values, err := scanRow(rows, len(columns))

View on GitHub (pinned to c0390bff16)

Solutions

Retry with the exact catalog casing (check ALL_TABLES for stored TABLE_NAME).
Drop or rename the duplicate case-variant table.
Standardize unquoted (upper/lower) identifier conventions in your schema.

Example fix

// before
ddl, err := srv.GetTableDDL("app", "orders") // ORDERS and Orders both exist

// after
ddl, err := srv.GetTableDDL("app", "ORDERS") // exact match wins

Defensive patterns

Strategy: validation

Validate before calling

rows, _ := db.Query(`SELECT TABLE_NAME FROM ALL_TABLES WHERE UPPER(TABLE_NAME)=UPPER(?)`, table)
var variants []string
for rows.Next() { var t string; rows.Scan(&t); variants = append(variants, t) }
rows.Close()
if len(variants) > 1 { return fmt.Errorf("ambiguous table name, catalog has: %v", variants) }

Try / catch

if strings.Contains(err.Error(), "table name is ambiguous") { return resolveWithExactCase(table) }

Prevention

Adopt a single-case identifier convention (e.g. all unquoted uppercase).
Rename or drop case-variant duplicates.
Pass exact catalog casing when calling DDL APIs.

When it happens

Trigger: Requesting DDL for 'orders' when the catalog holds both 'ORDERS' and 'Orders' tables in the same schema and the requested casing does not exactly match either.

Common situations: Mixed-case quoted identifiers created in the catalog; tools that created duplicate tables with different casing; a caller using lowercase names against a catalog storing uppercase.

Related errors

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