mattermost-community/focalboard · error

cannot commit category UUIDs transaction: %w

Error message

cannot commit category UUIDs transaction: %w

What it means

Error from SQLStore.RunCategoryUUIDIDMigration (server/services/store/sqlstore/data_migrations.go:165). The final step of the migration is tx.Commit(); if the commit fails, the DB discards all in-transaction ID rewrites and the error is wrapped as 'cannot commit category UUIDs transaction'.

Source

Thrown at server/services/store/sqlstore/data_migrations.go:165

		return nil
	}

	s.logger.Debug("Running category UUID ID migration")

	tx, txErr := s.db.BeginTx(context.Background(), nil)
	if txErr != nil {
		return txErr
	}

	if err := s.setSystemSetting(tx, CategoryUUIDIDMigrationKey, strconv.FormatBool(true)); err != nil {
		if rollbackErr := tx.Rollback(); rollbackErr != nil {
			s.logger.Error("category UUIDs transaction rollback error", mlog.Err(rollbackErr), mlog.String("methodName", "setSystemSetting"))
		}
		return fmt.Errorf("cannot mark migration as completed: %w", err)
	}

	if err := tx.Commit(); err != nil {
		return fmt.Errorf("cannot commit category UUIDs transaction: %w", err)
	}

	s.logger.Debug("category UUIDs migration finished successfully")
	return nil
}

func (s *SQLStore) RunFixCollationsAndCharsetsMigration() error {
	// This is for MySQL only
	if s.dbType != model.MysqlDBType {
		return nil
	}

	// get collation and charSet setting that Channels is using.
	// when personal server or unit testing, no channels tables exist so just set to a default.
	var collation string
	var charSet string
	var err error
	if os.Getenv("FOCALBOARD_UNIT_TESTING") == "1" {

View on GitHub (pinned to a84bbb65e3)

Solutions

1. Check the wrapped cause; connection-loss and serialization errors are safe to retry because the commit is atomic and the flag was never written.
2. Restore stable connectivity / wait out failover, then restart the app or re-trigger migrations.
3. Run the migration in a maintenance window to keep the transaction short and avoid contention.
4. Increase LB/proxy idle timeouts for migration connections.
5. Confirm success on retry via the 'category UUIDs migration finished successfully' debug log and the CategoryUUIDIDMigrationKey setting being true.

Example fix

// before
if err := store.RunCategoryUUIDIDMigration(); err != nil {
	return fmt.Errorf("migration failed: %v", err)
}
// after
if err := store.RunCategoryUUIDIDMigration(); err != nil {
	// transaction rolled back atomically; safe to retry once connectivity is restored
	return fmt.Errorf("category migration aborted at commit (retryable): %w", err)
}

if err := db.PingContext(ctx); err != nil { return err } // ensure DB is stable before a long rewrite transaction

func isCategoryCommitFailedError(err error) bool {
	return err != nil && strings.Contains(err.Error(), "cannot commit category UUIDs transaction")
}

err := store.RunCategoryUUIDIDMigration()
if err != nil {
	if isCategoryCommitFailedError(err) {
		// atomic rollback; wait for DB stability and retry
		time.Sleep(30 * time.Second)
		err = store.RunCategoryUUIDIDMigration()
	}
	if err != nil { return err }
}

When it happens

Trigger: Calling RunCategoryUUIDIDMigration when tx.Commit() fails: connection loss during the long-running rewrite transaction, serialization failure or deadlock detected at commit, or DB failover/restart mid-migration.

Common situations: Instances with many boards/categories making the migration transaction long-lived; flaky networks or aggressive load-balancer idle timeouts; managed-DB failovers during app startup; concurrent administrative DDL locking the tables at commit time.

Related errors

• cannot commit unique IDs transaction: %w
• cannot get migration state: %w
• cannot get blocks with same ID: %w
• cannot replace blockID %s: %w
• cannot mark migration as completed: %w

AI-assisted analysis of mattermost-community/focalboard@a84bbb65e3 (2026-08-30). Data as JSON: /api/errors/07be3f96bf6d89ff. Report an issue: GitHub.