bytebase/bytebase · error

schema is nil for %s

Error message

schema is nil for %s

What it means

The database metadata loaded fine, but metadata.GetSchemaMetadata("") returned nil — the default schema for the database is missing. Without the schema, the table (and its unique keys) cannot be located, so the disjoint-unique-key check aborts.

Source

Thrown at backend/plugin/parser/mysql/restore.go:245

	for _, column := range updateColumns {
		columnMap[strings.ToLower(column)] = true
	}

	if rCtx.GetDatabaseMetadataFunc == nil {
		return false, errors.Errorf("GetDatabaseMetadataFunc is nil")
	}

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

	schema := metadata.GetSchemaMetadata("")
	if schema == nil {
		return false, errors.Errorf("schema is nil for %s", originalDatabase)
	}

	tableMetadata := schema.GetTable(originalTable)
	if tableMetadata == nil {
		return false, errors.Errorf("table metadata is nil for %s.%s", originalDatabase, originalTable)
	}

	for _, index := range tableMetadata.GetProto().Indexes {
		if !index.Primary && !index.Unique {
			continue
		}
		if disjoint(index.Expressions, columnMap) {
			return true, nil
		}
	}

	return false, nil
}

View on GitHub (pinned to 1870550677)

Solutions

1. Refresh/re-sync the database metadata so the default schema and its tables are present
2. Verify the provider populates schema metadata under the empty schema name used by GetSchemaMetadata("")
3. Recreate the backup against a database whose metadata is current

md, err := loadMetadata(ctx, instanceID, db)
if err == nil && (md == nil || md.GetSchemaMetadata("") == nil) {
    return errors.New("default schema missing; refresh database metadata")
}

func schemaAvailable(md *storepb.DatabaseMetadata) bool {
    return md != nil && md.GetSchemaMetadata("") != nil
}

if err != nil && strings.Contains(err.Error(), "schema is nil") {
    // trigger a metadata sync, then retry the restore once
}

When it happens

Trigger: GenerateRestoreSQL -> doGenerate -> generateUpdateRestore -> hasDisjointUniqueKey where the metadata provider returns a DatabaseMetadata without a default (empty-name) schema — e.g. metadata synced when the database was empty or a provider that namespaces schemas differently.

Common situations: Metadata snapshot taken before any tables existed and never refreshed; MySQL metadata providers mapping no default schema; stale cache after the database was recreated.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• failed to get database schema: %q
• cannot find the type of `%s`.`%s`
• cannot find the type of `%s`.`%s`
• failed to classify columns
• failed to list databases names

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