What causes "schema metadata not found for %s" in bytebase/bytebase?

Verify the schema exists in the source database and update backupItem.SourceTable.Schema if it was renamed

schema metadata not found for %s

Error message

schema metadata not found for %s

What it means

Database metadata was loaded, but the schema named by backupItem.SourceTable.Schema (defaulting to "public" when empty) has no corresponding SchemaMetadata entry. The restore needs the schema's tables to build the INSERT..SELECT statement.

Source

Thrown at backend/plugin/parser/pg/restore.go:111

		return "", errors.Errorf("GetDatabaseMetadataFunc is required")
	}

	_, metadata, err := rCtx.GetDatabaseMetadataFunc(ctx, rCtx.InstanceID, sourceDatabase)
	if err != nil {
		return "", errors.Wrapf(err, "failed to get database metadata for %s", sourceDatabase)
	}

	if metadata == nil {
		return "", errors.Errorf("database metadata not found for %s", sourceDatabase)
	}

	schema := backupItem.SourceTable.Schema
	if schema == "" {
		schema = "public"
	}
	schemaMetadata := metadata.GetSchemaMetadata(schema)
	if schemaMetadata == nil {
		return "", errors.Errorf("schema metadata not found for %s", schema)
	}

	tableMetadata := schemaMetadata.GetTable(backupItem.SourceTable.Table)
	if tableMetadata == nil {
		return "", errors.Errorf("table metadata not found for %s.%s", schema, backupItem.SourceTable.Table)
	}

	backupSchema := backupItem.TargetTable.Schema
	backupTable := backupItem.TargetTable.Table
	originalSchema := schema
	originalTable := backupItem.SourceTable.Table
	quotedColumnList := quotePGColumns(restorableColumns(tableMetadata))

	var result string
	switch n := node.(type) {
	case *ast.DeleteStmt:
		result = fmt.Sprintf(`INSERT INTO "%s"."%s" (%s) SELECT %s FROM "%s"."%s";`, originalSchema, originalTable, quotedColumnList, quotedColumnList, backupSchema, backupTable)
	case *ast.UpdateStmt:

View on GitHub (pinned to 1870550677)

Solutions

Verify the schema exists in the source database and update backupItem.SourceTable.Schema if it was renamed
If the table lives in the default schema, ensure metadata actually contains it or record the correct explicit schema
Refresh/sync database metadata so the provider returns current schemas

Defensive patterns

Strategy: validation

Validate before calling

schema := backupItem.SourceTable.Schema
if schema == "" { schema = "public" }
if metadata.GetSchemaMetadata(schema) == nil {
    return fmt.Errorf("schema %q missing from metadata; cannot restore", schema)
}

Try / catch

if err != nil && strings.Contains(err.Error(), "schema metadata not found") {
    // refresh metadata or surface a schema-mismatch error to the user
}

Prevention

Record the explicit schema in backup items instead of relying on the "public" fallback
Re-sync schema metadata after any DDL migration affecting schemas
Validate backup items against current metadata before scheduling restore

When it happens

Trigger: backupItem.SourceTable.Schema names a schema absent from the fetched metadata — schema dropped/renamed since backup, or the backup item recorded a schema that never existed (empty schema on a database where the table is not in public).

Common situations: Restoring after a schema rename; backups taken before a migration removed the schema; non-public schema stored incorrectly so the code falls back to "public" and misses.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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