What causes "synonym not found: %s.%s" in t8y2/dbx?

Verify the synonym exists: SELECT * FROM ALL_SYNONYMS WHERE UPPER(SYNONYM_NAME)=UPPER(' ') AND UPPER(SCHEMA_NAME)=UPPER(' ');

t8y2/dbx · error

synonym not found: %s.%s

Error message

synonym not found: %s.%s

What it means

resolveCatalogSynonym looks up a synonym across candidate schemas and returns this error when zero candidates match. The synonym simply does not exist in the catalogs the driver queried, or the exact-case lookup plus the case-insensitive fallback both failed.

Source

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

		} else {
			candidate.Schema = schema.String
		}
		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
			}
		}

View on GitHub (pinned to c0390bff16)

Solutions

Verify the synonym exists: SELECT * FROM ALL_SYNONYMS WHERE UPPER(SYNONYM_NAME)=UPPER('<name>') AND UPPER(SCHEMA_NAME)=UPPER('<schema>');
Check you are connected to the intended database (the query filters on CURRENT_DB_ID).
Fix the schema/name arguments passed to the driver — including exact case if the catalog is case-sensitive.
Create the synonym if it is genuinely missing.

Example fix

// before
ddl, err := srv.GetObjectDDL("AP", "ORDER_SYNONYM") // synonym is actually in SALES schema

// after
ddl, err := srv.GetObjectDDL("SALES", "ORDER_SYNONYM")

Defensive patterns

Strategy: try-catch

Validate before calling

var n int
db.QueryRow(`SELECT COUNT(*) FROM ALL_SYNONYMS WHERE UPPER(SCHEMA_NAME)=UPPER(?) AND UPPER(SYNONYM_NAME)=UPPER(?)`, schema, name).Scan(&n)
if n == 0 { return fmt.Errorf("synonym %s.%s does not exist in this database", schema, name) }

Try / catch

if strings.HasPrefix(err.Error(), "synonym not found:") {
    return fmt.Errorf("%w: check schema/name and current database", err)
}

Prevention

Check existence before DDL extraction.
Confirm the connection string points at the intended database.
Keep migration scripts drop/create balanced so synonyms are not lost.

When it happens

Trigger: Requesting DDL/source for a synonym schema.name that has no rows in the synonym catalog — wrong schema, wrong name, or the synonym lives in a different database (CURRENT_DB_ID filter).

Common situations: Typo in the synonym name; querying the wrong schema; the synonym was dropped by another session; connecting to a different database instance than expected; quoting identifiers with unexpected casing in a case-sensitive catalog.

Related errors

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