What causes "failed to get linked database metadata for schema: %s" in bytebase/bytebase?

Inspect the wrapped root cause to distinguish registration vs connectivity problems

failed to get linked database metadata for schema: %s

Error message

failed to get linked database metadata for schema: %s

What it means

The query-span extractor resolved a table reference over a database link and called GetLinkedDatabaseMetadataFunc, which failed. The error is wrapped with the schema name used for the lookup, preserving the underlying cause (unknown link, connection failure, no metadata registered).

Source

Thrown at backend/plugin/parser/plsql/query_span_extractor.go:34

	defaultDatabase string

	ctes []*base.PseudoTable

	outerTableSources []base.TableSource
	tableSourcesFrom  []base.TableSource
}

func newQuerySpanExtractor(connectionDatabase string, gCtx base.GetQuerySpanContext) *querySpanExtractor {
	return &querySpanExtractor{
		defaultDatabase: connectionDatabase,
		gCtx:            gCtx,
	}
}

func (q *querySpanExtractor) getLinkedDatabaseMetadata(linkName string, schema string) (string, string, *model.DatabaseMetadata, error) {
	linkedInstanceID, databaseName, meta, err := q.gCtx.GetLinkedDatabaseMetadataFunc(q.ctx, q.gCtx.InstanceID, linkName, schema)
	if err != nil {
		return "", "", nil, errors.Wrapf(err, "failed to get linked database metadata for schema: %s", schema)
	}
	return linkedInstanceID, databaseName, meta, nil
}

func (q *querySpanExtractor) getDatabaseMetadata(schema string) (*model.DatabaseMetadata, error) {
	_, meta, err := q.gCtx.GetDatabaseMetadataFunc(q.ctx, q.gCtx.InstanceID, schema)
	if err != nil {
		return nil, errors.Wrapf(err, "failed to get database metadata for schema: %s", schema)
	}
	return meta, nil
}

func (q *querySpanExtractor) existsTableMetadata(resource base.SchemaResource) bool {
	if resource.Table == "DUAL" {
		return false
	}
	database := resource.Database
	if database == "" {

View on GitHub (pinned to 1870550677)

Solutions

Inspect the wrapped root cause to distinguish registration vs connectivity problems
Verify the database link name matches exactly (case, domain qualifiers) what is registered
Register or refresh metadata for the linked instance/schema
Fix connectivity/credentials to the remote instance if the root cause is a connection error

Defensive patterns

Strategy: fallback

Validate before calling

// Verify the link is known before analyzing SQL with @link references
if !knownLinks[strings.ToUpper(linkName)] {
	return fmt.Errorf("database link %q is not registered; register linked instance metadata first", linkName)
}

Try / catch

linked, db, meta, err := gCtx.GetLinkedDatabaseMetadataFunc(ctx, instanceID, linkName, schema)
if err != nil {
	return fmt.Errorf("dblink %q.%s unreachable: %w", linkName, schema, err)
}

Prevention

Register metadata for every linked instance referenced in analyzed SQL
Keep link names exactly matching SQL (including domain qualifiers)
Monitor remote instance connectivity for links used in production SQL

When it happens

Trigger: Parsing a query with a @dblink table reference (e.g. SELECT * FROM emp@remote.world) where gCtx.GetLinkedDatabaseMetadataFunc returns an error for (instanceID, linkName, schema) — link not configured, remote unreachable, or schema missing on the remote.

Common situations: Queries referencing database links that are not registered in Bytebase's metadata, links pointing to dropped/renamed remote databases, or credential/connectivity problems with the linked instance.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

AI-assisted analysis of bytebase/bytebase@1870550677 (2026-09-06). Data as JSON: /api/errors/4916dd2079270cee. Report an issue: GitHub.