username is required when auth_scheme = "sasl_digest"

Error message

username is required when auth_scheme = "sasl_digest"

What it means

When auth_scheme is sasl_digest, SASL DIGEST-MD5 authentication requires a username; openClient enforces this before attempting the connection. The check trims whitespace, so a whitespace-only username is also rejected.

Source

Thrown at agents/drivers/zookeeper/connection.go:159

	}
	result := map[string]any{}
	if info := databaseInfo(service.activeConfig); info != nil {
		result["databaseInfo"] = info
	}
	return result, nil
}

func openClient(config connectionConfig) (*clientSession, error) {
	if hasTLSOptions(config) {
		return nil, errors.New("ZooKeeper TLS is not supported")
	}
	authScheme := resolveAuthScheme(config)
	if authScheme != defaultAuthScheme && authScheme != saslDigestAuthScheme {
		return nil, fmt.Errorf("Unsupported auth_scheme %q; expected %q or %q", authScheme, defaultAuthScheme, saslDigestAuthScheme)
	}
	if authScheme == saslDigestAuthScheme {
		if strings.TrimSpace(config.Username) == "" {
			return nil, errors.New(`username is required when auth_scheme = "sasl_digest"`)
		}
		if config.Password == "" {
			return nil, errors.New(`password is required when auth_scheme = "sasl_digest"`)
		}
	}
	if config.BaseSleepTimeMS != nil && *config.BaseSleepTimeMS < 0 {
		return nil, errors.New("base_sleep_time_ms must be non-negative")
	}
	if config.MaxRetries != nil && *config.MaxRetries < 0 {
		return nil, errors.New("max_retries must be non-negative")
	}
	maxBufferSize, err := resolveMaxBufferSize(config)
	if err != nil {
		return nil, err
	}

	target, err := parseConnectTarget(connectionString(config))
	if err != nil {

View on GitHub (pinned to c0390bff16)

Solutions

Provide a non-empty username in the connection config alongside auth_scheme=sasl_digest
Verify the credential source (env var/secret manager) actually populated Username
Switch to the default auth scheme if SASL is not required
Ensure the username matches a ZooKeeper user with the needed ACLs

Example fix

// before
cfg := connectionConfig{AuthScheme: "sasl_digest", Password: pwd} // no username
// after
cfg := connectionConfig{AuthScheme: "sasl_digest", Username: "zkuser", Password: pwd}

Defensive patterns

Strategy: validation

Validate before calling

if cfg.AuthScheme == "sasl_digest" && strings.TrimSpace(cfg.Username) == "" {
    return errors.New("username is required when auth_scheme = sasl_digest")
}

Try / catch

_, err := openClient(cfg)
if err != nil && strings.Contains(err.Error(), "username is required") {
    return fmt.Errorf("supply SASL credentials: %w", err)
}

Prevention

When enabling sasl_digest, set username and password together in one change
Load credentials from a secret manager and assert non-empty before connect
Fail fast at startup if SASL env vars are missing
Keep the SASL username aligned with ZooKeeper ACL grants

When it happens

Trigger: connectionConfig has auth_scheme = "sasl_digest" and Username is empty or whitespace-only when openClient runs (via connect or testConnection).

Common situations: Setting auth_scheme to sasl_digest but forgetting credentials; credentials supplied via a secret that failed to load into the config; username field misnamed in a config file.

Related errors

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