{"record":{"id":"87c068f885dadf19","repo":"apache/pulsar","slug":"error-while-booting-gssapi-client","errorCode":null,"errorMessage":"error while booting GSSAPI client","messagePattern":"error while booting GSSAPI client","errorType":"exception","errorClass":"SaslException","httpStatus":null,"severity":"error","filePath":"pulsar-client-auth-sasl/src/main/java/org/apache/pulsar/client/impl/auth/PulsarSaslClient.java","lineNumber":85,"sourceCode":"        KerberosName serviceKerberosName = new KerberosName(serverPrincipal + \"@\" + clientKerberosName.getRealm());\n        final String serviceName = serviceKerberosName.getServiceName();\n        final String serviceHostname = serviceKerberosName.getHostName();\n        final String clientPrincipalName = clientKerberosName.toString();\n        log.info().attr(\"serverPrincipal\", serverPrincipal)\n                .log(\"Using JAAS/SASL/GSSAPI auth to connect to server\");\n\n        try {\n            this.saslClient = Subject.doAs(clientSubject, new PrivilegedExceptionAction<SaslClient>() {\n                @Override\n                public SaslClient run() throws SaslException {\n                    String[] mechs = {\"GSSAPI\"};\n                    return Sasl.createSaslClient(mechs, clientPrincipalName, serviceName, serviceHostname, null,\n                        new ClientCallbackHandler());\n                }\n            });\n        } catch (PrivilegedActionException err) {\n            log.error().exception(err.getCause()).log(\"GSSAPI client error\");\n            throw new SaslException(\"error while booting GSSAPI client\", err.getCause());\n        }\n\n        if (saslClient == null) {\n            throw new SaslException(\"Cannot create JVM SASL Client\");\n        }\n\n    }\n\n    public AuthData evaluateChallenge(final AuthData saslToken) throws AuthenticationException {\n        if (saslToken == null) {\n            throw new AuthenticationException(\"saslToken is null\");\n        }\n        try {\n            if (clientSubject != null) {\n                final byte[] retval = Subject.doAs(clientSubject, new PrivilegedExceptionAction<byte[]>() {\n                    @Override\n                    public byte[] run() throws SaslException {\n                        return saslClient.evaluateChallenge(saslToken.getBytes());","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-auth-sasl/src/main/java/org/apache/pulsar/client/impl/auth/PulsarSaslClient.java#L67-L103","documentation":"PulsarSaslClient creates the JVM SASL client (GSSAPI mechanism) inside Subject.doAs(...) via Sasl.createSaslClient; if that privileged action throws (PrivilegedActionException), the cause is wrapped in a SaslException with this message. It indicates the underlying SASL/GSSAPI/JNDI-Kerberos layer failed to instantiate the client mechanism — usually a Kerberos infrastructure problem (missing krb5.conf, bad principal/realm, no native GSS-API or JGSS failure), not a code bug.","triggerScenarios":"Sasl.createSaslClient({\"GSSAPI\"}, ...) throwing inside the privileged action — e.g. no default realm/krb5.conf found, client principal name unparseable, GSSException from JGSS initialization, or SASL provider missing GSSAPI support (atypical JVM).","commonSituations":"Missing or invalid /etc/krb5.conf (or -Djava.security.krb5.conf unset) so realm discovery fails; client principal's realm not resolvable; JDK without unrestricted JGSS/crypto policies; running in a minimal JRE lacking the SASL GSSAPI provider.","solutions":["Inspect the wrapped cause (err.getCause()) in logs — the 'GSSAPI client error' log line names the underlying GSSException.","Ensure krb5.conf is present and valid (set -Djava.security.krb5.conf=/etc/krb5.conf) and the realm/KDC are reachable.","Confirm a valid TGT exists (klist) and the JAAS subject's principal matches the keytab/kdc principal, including realm casing.","Run with -Dsun.security.jgss.debug=true and -Dsun.security.spnego.debug=true to diagnose; verify the JVM includes the GSSAPI SASL provider (full JDK, not stripped JRE)."],"exampleFix":"// before\njava -jar client.jar // GSSException: No valid credentials provided (Mechanism level: Failed to find any Kerberos tgt)\n// after\njava -Djava.security.krb5.conf=/etc/krb5.conf \\\n     -Dsun.security.jgss.debug=true \\\n     -Djava.security.auth.login.config=/etc/pulsar/jaas.conf \\\n     -jar client.jar // after kinit -kt client.keytab user@REALM","handlingStrategy":"try-catch","validationCode":"// Java: pre-flight Kerberos environment checks\nstatic void validateKerberosEnv() {\n    String krb5 = System.getProperty(\"java.security.krb5.conf\", \"/etc/krb5.conf\");\n    if (!new File(krb5).canRead()) throw new IllegalStateException(\"krb5.conf missing: \" + krb5);\n    // probe that JGSS is functional:\n    try {\n        org.ietf.jgss.GSSManager factory = org.ietf.jgss.GSSManager.getInstance();\n        factory.createName(\"user@REALM\", org.ietf.jgss.GSSName.NT_USER_NAME);\n    } catch (org.ietf.jgss.GSSException e) {\n        throw new IllegalStateException(\"GSS init failed: \" + e.getMessage(), e);\n    }\n}\n// also verify a TGT: klist or Subject.getSubject(AccessController.getContext())\n// has a KerberosTicket for krbtgt/REALM","typeGuard":null,"tryCatchPattern":"try {\n    PulsarSaslClient client = new PulsarSaslClient(host, serverType, subject);\n} catch (SaslException e) {\n    if (e.getMessage().contains(\"error while booting GSSAPI client\")) {\n        // e.getCause() is the GSSException/SaslException from createSaslClient\n        log.error(\"GSSAPI init failed: {} — check krb5.conf, KDC reachability and TGT\", e.getCause());\n        // optionally re-kinit and retry once\n    } else { throw e; }\n}","preventionTips":["kinit (or keytab login) before startup and refresh tickets (relogin) for long-running processes.","Ship a valid krb5.conf and set -Djava.security.krb5.conf; verify KDC reachability from the client host.","Use a full JDK — minimal/stripped JVMs may lack the GSSAPI SASL provider.","Enable -Dsun.security.jgss.debug=true in staging to catch GSS issues early."],"tags":["kerberos","gssapi","sasl","jvm","configuration"],"backgroundTag":"kerberos-login-failed","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}