What causes "failed to get a kerberos client" in argoproj/argo-workflows?

Provide keytabOptions (username, realm, keytab bytes) in the HDFS artifact krbOptions of the controller ConfigMap.

failed to get a kerberos client

Error message

failed to get a kerberos client

What it means

createKrbClient builds a Kerberos client for HDFS access from either a credential cache or a keytab. If the KrbOptions contain neither CCacheOptions nor KeytabOptions, it falls through to this generic error. It means the Kerberos configuration was recognized but carried no usable credential source.

Solutions

Provide keytabOptions (username, realm, keytab bytes) in the HDFS artifact krbOptions of the controller ConfigMap.
Alternatively supply ccacheOptions with a valid Kerberos credential cache.
Verify the keytab secret is mounted and its contents are base64-loaded into the ConfigMap correctly.
Check createKrbClient in workflow/artifacts/hdfs/util.go to confirm which branch (CCache/Keytab) your config is expected to hit.

Example fix

// before
hdfsArtifacts:
  - krbOptions:
      krbcfg: "..."
// after
hdfsArtifacts:
  - krbOptions:
      krbcfg: "..."
      keytabOptions:
        username: hdfs-user
        realm: EXAMPLE.COM
        keytab: <base64 keytab>

Defensive patterns

Strategy: validation

Validate before calling

func validateKrbOptions(o *KrbOptions) error {
	if o == nil {
		return nil
	}
	if o.CCacheOptions == nil && o.KeytabOptions == nil {
		return fmt.Errorf("krbOptions needs either ccacheOptions or keytabOptions")
	}
	return nil
}

Type guard

func hasKrbCredentialSource(o *KrbOptions) bool {
	return o != nil && (o.CCacheOptions != nil || o.KeytabOptions != nil)
}

Try / catch

cli, err := createHDFSClient(addrs, user, prot, krbOpts)
if err != nil && strings.Contains(err.Error(), "failed to get a kerberos client") {
	// config omits ccache/keytab: surface a config error to the operator
}

Prevention

Always pair kerberos config with keytab (preferred) or a valid ccache
Mount keytab secrets and verify base64 encoding before deploying
Lint the controller ConfigMap for complete hdfsArtifacts krbOptions
Test HDFS artifact access with a canary workflow after config changes

When it happens

Trigger: Configuring HDFS artifact access with kerberos enabled (hdfsArtifact with krbOptions) but providing only krbcfg (config string) or servicePrincipalName while omitting both the ccache and keytab material; createHDFSClient then returns this error before any connection attempt.

Common situations: Misconfigured argo worklfow controller ConfigMap where users set `keytab`/`ccache` data in the wrong field or forget to mount the keytab secret; partially copied sample configs that only include the krb5.conf section.

Related errors

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

Appendix: source

Thrown at workflow/artifacts/hdfs/util.go:57

		if cacheErr != nil {
			return nil, cacheErr
		}
		return client, nil
	} else if krbOptions.KeytabOptions != nil {
		client := krb.NewWithKeytab(
			krbOptions.KeytabOptions.Username,
			krbOptions.KeytabOptions.Realm,
			&krbOptions.KeytabOptions.Keytab,
			krbConfig,
		)
		err = client.Login()
		if err != nil {
			return nil, err
		}
		return client, nil
	}

	return nil, fmt.Errorf("failed to get a kerberos client")
}

View on GitHub (pinned to 35bff19146)