bytebase/bytebase · error

failed to init SASL environment

Error message

failed to init SASL environment

What it means

When the data source's SASL config carries a Kerberos mechanism, Open boots a Kerberos environment (krb5 config, keytab, ccache) under a mutex before connecting. If util.BootKerberosEnv fails — bad krb5.conf, missing keytab, unreadable credentials cache — the error is wrapped with this message.

Source

Thrown at backend/plugin/db/hive/hive.go:94

	return dsn
}

func (d *Driver) Open(ctx context.Context, _ storepb.Engine, config db.ConnectionConfig) (db.Driver, error) {
	if config.DataSource.Host == "" {
		return nil, errors.Errorf("hostname not set")
	}

	// Build DSN connection string
	connString := buildHiveDSN(config)

	// Handle Kerberos authentication if needed
	if t, ok := config.DataSource.GetSaslConfig().GetMechanism().(*storepb.SASLConfig_KrbConfig); ok {
		// Kerberos environment mutex
		util.Lock.Lock()
		defer util.Lock.Unlock()

		if err := util.BootKerberosEnv(t); err != nil {
			return nil, errors.Wrapf(err, "failed to init SASL environment")
		}
	}

	// Open database connection using v2 driver
	sqlDB, err := sql.Open("hive", connString)
	if err != nil {
		return nil, errors.Wrap(err, "failed to open hive connection")
	}

	// Configure connection pool (Hive doesn't support many concurrent connections well)
	sqlDB.SetMaxOpenConns(5)
	sqlDB.SetMaxIdleConns(2)
	sqlDB.SetConnMaxLifetime(0) // connections don't expire

	// Verify connection works
	if err := sqlDB.PingContext(ctx); err != nil {
		sqlDB.Close()
		return nil, errors.Wrap(err, "failed to ping hive server")

View on GitHub (pinned to 1870550677)

Solutions

1. Verify /etc/krb5.conf (or KRB5_CONFIG) exists and points at the correct KDC.
2. Check the keytab file path and principal in the SASL KrbConfig are correct and the file is readable by the process.
3. Run klist -k <keytab> and kinit -kt <keytab> <principal> manually to reproduce and validate the setup.
4. Ensure clock sync (NTP) between the client and the KDC to avoid ticket validation failures.

Example fix

// before
saslConfig: { mechanism: { krbConfig: { principal: "hive/_HOST", krb5ConfPath: "", keytabPath: "" } } }
// after
saslConfig: { mechanism: { krbConfig: { principal: "hive/_HOST@REALM.EXAMPLE.COM", krb5ConfPath: "/etc/krb5.conf", keytabPath: "/etc/security/keytabs/hive.keytab" } } }

if krb := krbConfig; krb != nil {
    if _, err := os.Stat(krb.Krb5ConfPath); err != nil { return fmt.Errorf("krb5.conf missing: %w", err) }
    if _, err := os.Stat(krb.KeytabPath); err != nil { return fmt.Errorf("keytab missing: %w", err) }
}

driver, err := hiveDriver.Open(ctx, engine, config)
var envErr *errors.Error
if errors.As(err, &envErr) && strings.Contains(err.Error(), "failed to init SASL environment") {
    // surface Kerberos env guidance to the operator
}

When it happens

Trigger: Opening a Hive connection with SASLConfig_KrbConfig set while the Kerberos environment cannot be initialized: missing/invalid KRB5_CONFIG, missing keytab file, wrong principal, or kinit-style setup failure inside BootKerberosEnv.

Common situations: Kerberized Hive clusters where the container/host lacks /etc/krb5.conf; keytab path wrong or not mounted; principal not matching the KDC entry; clock skew against the KDC; running as a user without access to the ccache.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• data source %q connects somewhere new, so its Kerberos keyta
• failed to execute command kinit: %s
• "parent" field is required
• identity provider with name ${update.name} not found
• access token expired, please reconnect

AI-assisted analysis of bytebase/bytebase@1870550677 (2026-09-06). Data as JSON: /api/errors/319ded98f93cf50b. Report an issue: GitHub.