{"record":{"id":"4916dd2079270cee","repo":"bytebase/bytebase","slug":"failed-to-get-linked-database-metadata-for-schema","errorCode":null,"errorMessage":"failed to get linked database metadata for schema: %s","messagePattern":"failed to get linked database metadata for schema: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"backend/plugin/parser/plsql/query_span_extractor.go","lineNumber":34,"sourceCode":"\tdefaultDatabase string\n\n\tctes []*base.PseudoTable\n\n\touterTableSources []base.TableSource\n\ttableSourcesFrom  []base.TableSource\n}\n\nfunc newQuerySpanExtractor(connectionDatabase string, gCtx base.GetQuerySpanContext) *querySpanExtractor {\n\treturn &querySpanExtractor{\n\t\tdefaultDatabase: connectionDatabase,\n\t\tgCtx:            gCtx,\n\t}\n}\n\nfunc (q *querySpanExtractor) getLinkedDatabaseMetadata(linkName string, schema string) (string, string, *model.DatabaseMetadata, error) {\n\tlinkedInstanceID, databaseName, meta, err := q.gCtx.GetLinkedDatabaseMetadataFunc(q.ctx, q.gCtx.InstanceID, linkName, schema)\n\tif err != nil {\n\t\treturn \"\", \"\", nil, errors.Wrapf(err, \"failed to get linked database metadata for schema: %s\", schema)\n\t}\n\treturn linkedInstanceID, databaseName, meta, nil\n}\n\nfunc (q *querySpanExtractor) getDatabaseMetadata(schema string) (*model.DatabaseMetadata, error) {\n\t_, meta, err := q.gCtx.GetDatabaseMetadataFunc(q.ctx, q.gCtx.InstanceID, schema)\n\tif err != nil {\n\t\treturn nil, errors.Wrapf(err, \"failed to get database metadata for schema: %s\", schema)\n\t}\n\treturn meta, nil\n}\n\nfunc (q *querySpanExtractor) existsTableMetadata(resource base.SchemaResource) bool {\n\tif resource.Table == \"DUAL\" {\n\t\treturn false\n\t}\n\tdatabase := resource.Database\n\tif database == \"\" {","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/bytebase/bytebase/blob/1870550677fe08f0d2a78c07acd27541464eb945/backend/plugin/parser/plsql/query_span_extractor.go#L16-L52","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// Verify the link is known before analyzing SQL with @link references\nif !knownLinks[strings.ToUpper(linkName)] {\n\treturn fmt.Errorf(\"database link %q is not registered; register linked instance metadata first\", linkName)\n}","typeGuard":null,"tryCatchPattern":"linked, db, meta, err := gCtx.GetLinkedDatabaseMetadataFunc(ctx, instanceID, linkName, schema)\nif err != nil {\n\treturn fmt.Errorf(\"dblink %q.%s unreachable: %w\", linkName, schema, err)\n}","preventionTips":["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"],"tags":["plsql","dblink","metadata","query-span"],"backgroundTag":"database-query-failed","analyzedSha":"1870550677fe08f0d2a78c07acd27541464eb945","analyzedAt":"2026-09-06T21:16:13.665Z","contentChangedAt":"2026-09-06T21:16:13.665Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}