argoproj/argo-workflows · error

database session is not available for mutex %s

Error message

database session is not available for mutex %s

What it means

The sync Manager can only create a database-backed mutex when a database session proxy has been configured on the manager (sm.dbInfo.SessionProxy). If a sync/mutex resource is declared with kind database but the controller has no DB-backed sync configured, initialization fails. This prevents silently using a mutex that would have no persistent backing.

Source

Thrown at workflow/sync/sync_manager.go:874

			return nil, fmt.Errorf("database session is not available for semaphore %s", semaphoreName)
		}
		return newDatabaseSemaphore(ctx, semaphoreName, lock.getDBKey(), sm.nextWorkflow, sm.dbInfo, sm.syncLimitCacheTTL)
	default:
		return nil, fmt.Errorf("invalid lock kind %s when initializing semaphore", lock.getKind())
	}
}

func (sm *Manager) initializeMutex(ctx context.Context, mutexName string) (semaphore, error) {
	lock, err := DecodeLockName(ctx, mutexName)
	if err != nil {
		return nil, err
	}
	switch lock.getKind() {
	case lockKindMutex:
		return newInternalMutex(mutexName, sm.nextWorkflow), nil
	case lockKindDatabase:
		if sm.dbInfo.SessionProxy == nil {
			return nil, fmt.Errorf("database session is not available for mutex %s", mutexName)
		}
		return newDatabaseMutex(mutexName, lock.getDBKey(), sm.nextWorkflow, sm.dbInfo), nil
	default:
		return nil, fmt.Errorf("invalid lock kind %s when initializing mutex", lock.getKind())
	}
}

func (sm *Manager) backgroundNotifier(ctx context.Context, period *int) {
	sm.log.WithField("pollInterval", syncdb.SecondsToDurationWithDefault(period, syncdb.DefaultDBHeartbeatSeconds)).
		Info(ctx, "Starting background notification for sync locks")
	go wait.UntilWithContext(ctx, func(_ context.Context) {
		sm.lock.Lock()
		for _, lock := range sm.syncLockMap {
			lock.probeWaiting(ctx)
		}
		sm.lock.Unlock()
	},
		syncdb.SecondsToDurationWithDefault(period, syncdb.DefaultDBPollSeconds),

View on GitHub (pinned to 35bff19146)

Solutions

1. Configure database-backed sync on the workflow-controller (set the sync DB config / syncConfig so dbInfo.SessionProxy is populated) and restart the controller
2. Change the mutex/lock kind from 'database' back to 'configmap' in the sync ConfigMap if DB sync is not intended
3. Verify the sync database is reachable and the controller logs show successful DB session setup before submitting workflows

Example fix

// before (controller lacks DB sync, workflow uses database mutex)
synchronize: { mutex: { name: mydbmutex } }  // kind: database
// after (either fix controller config or use configmap lock)
synchronize: { mutex: { name: mymutex } }  // with kind: configmap in sync ConfigMap

// before submitting, confirm the sync DB config is present
kind := getSyncLockKind(configMap, lockName)
if kind == "database" && controllerSyncDBConfig == nil {
    return fmt.Errorf("database mutex %s requires controller sync DB configuration", lockName)
}

func isDatabaseSyncConfigured(sm *sync.Manager) bool {
    return sm != nil && sm.DBInfo != nil && sm.DBInfo.SessionProxy != nil
}

err := wf.Wait(ctx)
if err != nil && strings.Contains(err.Error(), "database session is not available for mutex") {
    // fall back to configmap-based mutex or alert operator to enable DB sync
}

When it happens

Trigger: A workflow references a mutex/sync lock whose ConfigMap-declared kind is 'database' while the workflow-controller was started without database sync configuration (syncConfig with a DB connection), so sm.dbInfo.SessionProxy is nil when initializeMutex runs via prepAcquire.

Common situations: Operators switch a lock's kind from configmap to database without updating the controller's sync database configuration; fresh deployments missing the sync DB configmap/DB connection; kind misconfiguration in the workflow's synchronize section.

Related errors

• synchronization database session is not available
• invalid lock kind %s when initializing mutex
• unsupported db type %s
• maxRetries cannot be less than 0
• baseDelay cannot be less than 0

AI-assisted analysis of argoproj/argo-workflows@35bff19146 (2026-09-03). Data as JSON: /api/errors/d3ea1e0c7ba80358. Report an issue: GitHub.