registerThrottler(): throttler with name '%v' is already reg

Error message

registerThrottler(): throttler with name '%v' is already registered

What it means

The throttler manager keys throttlers by name; registerThrottler rejects duplicate names to keep the registry unambiguous. Registering the same name twice means either a lifecycle bug or a genuine name collision.

Source

Thrown at go/vt/throttler/manager.go:81

type managerImpl struct {
	// mu guards all fields in this group.
	mu sync.Mutex
	// throttlers tracks all running throttlers (by their name).
	throttlers map[string]Throttler
}

func newManager() *managerImpl {
	return &managerImpl{
		throttlers: make(map[string]Throttler),
	}
}

func (m *managerImpl) registerThrottler(name string, throttler Throttler) error {
	m.mu.Lock()
	defer m.mu.Unlock()

	if _, ok := m.throttlers[name]; ok {
		return fmt.Errorf("registerThrottler(): throttler with name '%v' is already registered", name)
	}
	m.throttlers[name] = throttler
	return nil
}

func (m *managerImpl) unregisterThrottler(name string) {
	m.mu.Lock()
	defer m.mu.Unlock()

	if _, ok := m.throttlers[name]; !ok {
		log.Error(fmt.Sprintf("unregisterThrottler(): throttler with name '%v' is not registered", name))
		return
	}
	delete(m.throttlers, name)
}

// MaxRates returns the max rate of all known throttlers.
func (m *managerImpl) MaxRates() map[string]int64 {

View on GitHub (pinned to 01a25a7d17)

Solutions

Call UnregisterThrottler before re-registering the same name
Choose a unique name per throttler instance (include cell/keyspace in the name)
If registration happens at startup, make idempotent: check for existing name first
Check shutdown path ensures unregisterThrottler runs even on error

Example fix

// before
manager.RegisterThrottler("keyspace/shard", th) // twice
// after
manager.UnregisterThrottler("keyspace/shard")
err := manager.RegisterThrottler("keyspace/shard", th)

Defensive patterns

Strategy: validation

Validate before calling

if _, exists := registeredNames[name]; exists {
    manager.UnregisterThrottler(name)
}
return manager.RegisterThrottler(name, th)

Try / catch

if err := manager.RegisterThrottler(name, th); err != nil {
    if strings.Contains(err.Error(), "already registered") {
        manager.UnregisterThrottler(name)
        return manager.RegisterThrottler(name, th)
    }
    return err
}

Prevention

Unregister on shutdown via defer
Include cell/keyspace in throttler names to avoid collisions
Make throttler startup idempotent

When it happens

Trigger: Calling Manager.RegisterThrottler (newThrottlerFromConfig) with a name that already exists in the manager's throttlers map, e.g. registering a throttler twice for one cell/keyspace or after a partial shutdown that didn't unregister.

Common situations: Two throttler instances started with the same keyspace/cell name, double initialization during reload, or a crashed process re-registering without calling UnregisterThrottler.

Related errors

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/34cffa7b96240e0d. Report an issue: GitHub.