t8y2/dbx · error

Kerberos requires krb5.conf or Windows SSPI

Error message

Kerberos requires krb5.conf or Windows SSPI

What it means

When Kerberos authentication is enabled (kerberos.Enabled), the driver needs a way to obtain Kerberos credentials. On non-Windows platforms it requires a krb5.conf configuration file path (explicitly set, via KRB5_CONFIG, or found at a default location). If no config path was resolved and SSPI (Windows integrated auth) is not enabled, configuration cannot proceed and this error is thrown from finalizeKerberosConfig.

Solutions

  1. Install or mount a valid krb5.conf and set kerberos.ConfigPath (or KRB5_CONFIG) to its path.
  2. Set the KRB5_CONFIG environment variable to the krb5.conf location before starting the process.
  3. On Windows, confirm the code path allows SSPI, or explicitly set kerberos.UseSSPI = true.
  4. In containers, add the krb5.conf file (e.g. COPY krb5.conf /etc/krb5.conf) and install krb5 userland packages.

Example fix

// before
cfg := map[string]string{"authentication": "kerberos"}
// after
cfg := map[string]string{"authentication": "kerberos", "kerberosConfigPath": "/etc/krb5.conf"}
// or: os.Setenv("KRB5_CONFIG", "/etc/krb5.conf")
Defensive patterns

Strategy: validation

Validate before calling

func ensureKrb5Setup(useSSPI bool, configPath, envKrb5 string) error {
	if runtime.GOOS == "windows" && useSSPI { return nil }
	if configPath != "" {
		if _, err := os.Stat(configPath); err != nil { return fmt.Errorf("krb5.conf not found: %w", err) }
		return nil
	}
	if envKrb5 != "" {
		if _, err := os.Stat(envKrb5); err != nil { return fmt.Errorf("KRB5_CONFIG points to missing file: %w", err) }
		return nil
	}
	for _, p := range []string{"/etc/krb5.conf", "/etc/krb5/krb5.conf"} {
		if _, err := os.Stat(p); err == nil { return nil }
	}
	return errors.New("no krb5.conf available; set KRB5_CONFIG or kerberosConfigPath")
}
// call before enabling kerberos auth

Try / catch

if err := driver.Connect(cfg); err != nil {
	if strings.Contains(err.Error(), "requires krb5.conf") {
		return fmt.Errorf("kerberos setup incomplete: install krb5.conf or set KRB5_CONFIG: %w", err)
	}
	return err
}

Prevention

When it happens

Trigger: Enabling Kerberos auth in the connection config on Linux/macOS without: a ConfigPath, a KRB5_CONFIG environment variable, a krb5.conf at the default location (/etc/krb5.conf etc.), or kerberos.UseSSPI on Windows.

Common situations: Running in a minimal Docker image (scratch/alpine) that lacks /etc/krb5.conf; forgetting to mount or copy krb5.conf into the container; KRB5_CONFIG pointing to a missing file; enabling kerberos=true in a connection string on a machine without any Kerberos setup.

Related errors

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/d3dd05e7e5abde3b. Report an issue: GitHub.

Appendix: source

Thrown at agents/drivers/argo-go/config.go:938

	if kerberos.ConfigPath == "" {
		if candidate := defaultKerberosConfigPath(); fileExists(candidate) {
			kerberos.ConfigPath = candidate
		}
	}
	if !kerberos.UseTicketCache && kerberos.CCachePath == "" {
		if candidate := defaultKerberosCCachePath(); fileExists(candidate) {
			kerberos.CCachePath = candidate
			kerberos.UseTicketCache = true
		}
	}
	if runtime.GOOS == "windows" && kerberos.ConfigPath == "" && kerberos.KeytabPath == "" && kerberos.CCachePath == "" {
		kerberos.UseSSPI = true
	}
	if kerberos.UseSSPI {
		return nil
	}
	if kerberos.ConfigPath == "" {
		return errors.New("Kerberos requires krb5.conf or Windows SSPI")
	}
	if kerberos.ClientPrincipal == "" && !kerberos.UseTicketCache && !kerberos.UseKeytab {
		kerberos.ClientPrincipal = strings.TrimSpace(config.Username)
	}
	if kerberos.KeytabPath != "" {
		kerberos.UseKeytab = true
	}
	if kerberos.CCachePath != "" {
		kerberos.UseTicketCache = true
	}
	kerberos.Realm = firstNonEmpty(kerberos.Realm, realmFromPrincipal(kerberos.ClientPrincipal))
	if !kerberos.UseTicketCache && !kerberos.UseKeytab && (kerberos.ClientPrincipal == "" || kerberos.Password == "") {
		return errors.New("Kerberos requires SSPI, credential cache, keytab, or principal and password")
	}
	return nil
}

var jaasOptionPattern = regexp.MustCompile(`(?i)\b(principal|keytab|ticketcache|usekeytab|useticketcache)\s*=\s*("(?:\\.|[^"])*"|'(?:\\.|[^'])*'|[^\s;]+)`)

View on GitHub (pinned to c0390bff16)