{"record":{"id":"319ded98f93cf50b","repo":"bytebase/bytebase","slug":"failed-to-init-sasl-environment","errorCode":null,"errorMessage":"failed to init SASL environment","messagePattern":"failed to init SASL environment","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"backend/plugin/db/hive/hive.go","lineNumber":94,"sourceCode":"\treturn dsn\n}\n\nfunc (d *Driver) Open(ctx context.Context, _ storepb.Engine, config db.ConnectionConfig) (db.Driver, error) {\n\tif config.DataSource.Host == \"\" {\n\t\treturn nil, errors.Errorf(\"hostname not set\")\n\t}\n\n\t// Build DSN connection string\n\tconnString := buildHiveDSN(config)\n\n\t// Handle Kerberos authentication if needed\n\tif t, ok := config.DataSource.GetSaslConfig().GetMechanism().(*storepb.SASLConfig_KrbConfig); ok {\n\t\t// Kerberos environment mutex\n\t\tutil.Lock.Lock()\n\t\tdefer util.Lock.Unlock()\n\n\t\tif err := util.BootKerberosEnv(t); err != nil {\n\t\t\treturn nil, errors.Wrapf(err, \"failed to init SASL environment\")\n\t\t}\n\t}\n\n\t// Open database connection using v2 driver\n\tsqlDB, err := sql.Open(\"hive\", connString)\n\tif err != nil {\n\t\treturn nil, errors.Wrap(err, \"failed to open hive connection\")\n\t}\n\n\t// Configure connection pool (Hive doesn't support many concurrent connections well)\n\tsqlDB.SetMaxOpenConns(5)\n\tsqlDB.SetMaxIdleConns(2)\n\tsqlDB.SetConnMaxLifetime(0) // connections don't expire\n\n\t// Verify connection works\n\tif err := sqlDB.PingContext(ctx); err != nil {\n\t\tsqlDB.Close()\n\t\treturn nil, errors.Wrap(err, \"failed to ping hive server\")","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/bytebase/bytebase/blob/1870550677fe08f0d2a78c07acd27541464eb945/backend/plugin/db/hive/hive.go#L76-L112","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify /etc/krb5.conf (or KRB5_CONFIG) exists and points at the correct KDC.","Check the keytab file path and principal in the SASL KrbConfig are correct and the file is readable by the process.","Run klist -k <keytab> and kinit -kt <keytab> <principal> manually to reproduce and validate the setup.","Ensure clock sync (NTP) between the client and the KDC to avoid ticket validation failures."],"exampleFix":"// before\nsaslConfig: { mechanism: { krbConfig: { principal: \"hive/_HOST\", krb5ConfPath: \"\", keytabPath: \"\" } } }\n// after\nsaslConfig: { mechanism: { krbConfig: { principal: \"hive/_HOST@REALM.EXAMPLE.COM\", krb5ConfPath: \"/etc/krb5.conf\", keytabPath: \"/etc/security/keytabs/hive.keytab\" } } }","handlingStrategy":"validation","validationCode":"if krb := krbConfig; krb != nil {\n    if _, err := os.Stat(krb.Krb5ConfPath); err != nil { return fmt.Errorf(\"krb5.conf missing: %w\", err) }\n    if _, err := os.Stat(krb.KeytabPath); err != nil { return fmt.Errorf(\"keytab missing: %w\", err) }\n}","typeGuard":null,"tryCatchPattern":"driver, err := hiveDriver.Open(ctx, engine, config)\nvar envErr *errors.Error\nif errors.As(err, &envErr) && strings.Contains(err.Error(), \"failed to init SASL environment\") {\n    // surface Kerberos env guidance to the operator\n}","preventionTips":["Mount /etc/krb5.conf and the keytab into containers before enabling Kerberos auth","Test kinit with the same keytab/principal on the host running the app","Keep client clocks NTP-synced with the KDC"],"tags":["kerberos","sasl","authentication","hive"],"backgroundTag":"missing-env-var","analyzedSha":"1870550677fe08f0d2a78c07acd27541464eb945","analyzedAt":"2026-09-06T21:16:13.665Z","contentChangedAt":"2026-09-06T21:16:13.665Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}