argoproj/argo-workflows · critical

must specify at least one auth mode

Error message

must specify at least one auth mode

What it means

NewGatekeeper builds the Argo Server's auth interceptor and requires at least one authentication mode (client, server, or sso). If the Modes map derived from server configuration is empty, startup fails immediately with 'must specify at least one auth mode'. This is a fail-fast configuration guard so the API server is never exposed without a defined auth strategy.

Source

Thrown at server/auth/gatekeeper.go:74

type ClientForAuthorization func(authorization string, config *rest.Config) (*rest.Config, *servertypes.Clients, error)

type gatekeeper struct {
	Modes Modes
	// global clients, not to be used if there are better ones
	clients                *servertypes.Clients
	restConfig             *rest.Config
	ssoIf                  sso.Interface
	clientForAuthorization ClientForAuthorization
	// The namespace the server is installed in.
	namespace    string
	ssoNamespace string
	namespaced   bool
	cache        *cache.ResourceCache
}

func NewGatekeeper(modes Modes, clients *servertypes.Clients, restConfig *rest.Config, ssoIf sso.Interface, clientForAuthorization ClientForAuthorization, namespace string, ssoNamespace string, namespaced bool, cache *cache.ResourceCache) (Gatekeeper, error) {
	if len(modes) == 0 {
		return nil, fmt.Errorf("must specify at least one auth mode")
	}
	return &gatekeeper{
		modes,
		clients,
		restConfig,
		ssoIf,
		clientForAuthorization,
		namespace,
		ssoNamespace,
		namespaced,
		cache,
	}, nil
}

func (s *gatekeeper) UnaryServerInterceptor() grpc.UnaryServerInterceptor {
	return func(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (resp any, err error) {
		ctx, err = s.ContextWithRequest(ctx, req)
		if err != nil {

View on GitHub (pinned to 35bff19146)

Solutions

1. Set authorization mode(s) in the workflow-controller-configmap `server.authorizationMode` to one or more of: client, server, sso.
2. If launching manually, pass `--auth-mode client --auth-mode server` (and/or sso) to `argo server`.
3. Check helm chart values (server.authMode / extraArgs) so at least one mode reaches the server args.
4. Validate the configmap for typos — an unrecognized mode value is dropped, potentially leaving zero modes.
5. If you intended SSO only, ensure sso.enabled=true and sso config (issuer, clientId) is valid so the sso mode registers.

Example fix

// before: workflow-controller-configmap.yaml
data:
  config: |
    server:
      sso:
        enabled: false   # SSO off and no authorizationMode -> zero modes
// after
data:
  config: |
    server:
      authorizationMode: client,server
      sso:
        enabled: false

modes := parseAuthModes(config.Server.AuthorizationMode, ssoEnabled)
if len(modes) == 0 {
    return fmt.Errorf("config error: enable at least one of client/server/sso in server.authorizationMode before starting argo server")
}

func hasAuthMode(cfg Config) bool {
    return len(cfg.Server.AuthorizationMode) > 0 || cfg.Server.SSO.Enabled
}

gk, err := auth.NewGatekeeper(modes, clients, restConfig, ssoIf, clientForAuth, ns, ssoNs, namespaced, cache)
if err != nil {
    if strings.Contains(err.Error(), "must specify at least one auth mode") {
        log.Fatalf("server misconfigured: set server.authorizationMode (client|server|sso) in the workflow-controller-configmap")
    }
    return err
}

When it happens

Trigger: Starting `argo server` with a workflow-controller-configmap whose `server` section enables no auth methods: e.g. sso.enabled=false while authorizationMode excludes both client and server, or `--auth-mode` flags omitted entirely, or an invalid authorizationMode value that fails to parse leaving zero modes.

Common situations: Misediting the server authMode config when disabling SSO; deploying with a configmap that sets `authorization: ''`; helm values that empty the auth mode list; upgrading and the deprecated auth-mode key no longer being read.

Related errors

• AuthSupplier cannot be empty when connecting to Argo Server
• failed to compile sso.filterGroupRegex: %s %w
• failed to validate workflow template instanceid: %w
• malformed workflow template parameter "%s": valueFrom is nil
• failed to compile workflow template parameter %s expression:

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