synonym name is ambiguous: %s.%s; specify the catalog's exac

Error message

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

What it means

When resolveCatalogSynonym finds more than one synonym matching schema.name case-insensitively, it cannot pick one and throws this error, telling the caller to specify the catalog's exact case. Ambiguity arises because the catalog stores multiple rows differing only by identifier case.

Source

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

		}
		candidates = append(candidates, candidate)
	}
	return candidates, rows.Err()
}

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

func xuguSequenceNumber(value any) string {
	return strings.TrimSpace(xuguString(value))
}

func (s *server) getTableDDL(schema, table string) (string, error) {
	// Resolve the catalog's stored casing before issuing exact metadata lookups,
	// so emitted DDL quotes the original names and preserves double-quoted
	// schema/table/column spellings.
	if strings.TrimSpace(schema) != "" {
		if err := s.setSchema(schema); err != nil {
			if !isXuguMetadataAccessError(err) {
				return "", err
			}
		}
	}
	catalogSchema, catalogTable, err := s.resolveCatalogTableName(schema, table)

View on GitHub (pinned to c0390bff16)

Solutions

Re-send the request with the synonym's exact catalog casing (query ALL_SYNONYMS to see the stored name).
Drop the duplicate synonyms so only one case variant remains.
If the tooling generates names programmatically, normalize identifier casing consistently when creating objects.

Example fix

// before
ddl, err := srv.GetObjectDDL("APP", "orders") // matches ORDERS and Orders

// after
ddl, err := srv.GetObjectDDL("APP", "Orders") // exact catalog casing

Defensive patterns

Strategy: validation

Validate before calling

rows, _ := db.Query(`SELECT SCHEMA_NAME, SYNONYM_NAME FROM ALL_SYNONYMS WHERE UPPER(SCHEMA_NAME)=UPPER(?) AND UPPER(SYNONYM_NAME)=UPPER(?)`, schema, name)
var matches []string
for rows.Next() { var s, n string; rows.Scan(&s, &n); matches = append(matches, s+"."+n) }
rows.Close()
if len(matches) > 1 { return fmt.Errorf("ambiguous synonym; exact matches: %v", matches) }

Try / catch

if strings.Contains(err.Error(), "synonym name is ambiguous") {
    // re-run with exact casing after listing candidates
    return retryWithExactCase(schema, name)
}

Prevention

Avoid quoted mixed-case identifiers when creating objects.
Deduplicate case-variant synonyms in the schema.
Always request objects with their exact stored catalog casing.

When it happens

Trigger: Calling the synonym DDL/source path with a name like 'orders' when the catalog contains both 'ORDERS' and 'Orders' synonyms in the same schema, and neither exact-cases match the requested string.

Common situations: Objects created with quoted mixed-case identifiers on a case-sensitive catalog; migration tools that duplicated objects with different casing; querying with the wrong casing so the exact-match pass misses and the fallback matches many rows.

Related errors

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