quarkusio/quarkus · error · IllegalStateException

The org.postgresql.sspi.SSPIClient is not available on Graal

Error message

The org.postgresql.sspi.SSPIClient is not available on GraalVM

What it means

DisableSSPIClient is a GraalVM @Substitute replacing org.postgresql.jdbc.SSPIRunnable/createSSPI wiring of org.postgresql.sspi.SSPIClient. Windows SSPI (integrated GSS/SSPI authentication) is not supported in native images, so the substitute always throws IllegalStateException. It means a native-image build tried to create the SSPI client for Windows integrated authentication.

Source

Thrown at extensions/jdbc/jdbc-postgresql/runtime/src/main/java/io/quarkus/jdbc/postgresql/runtime/graal/DisableSSPIClient.java:17

package io.quarkus.jdbc.postgresql.runtime.graal;

import org.postgresql.core.PGStream;
import org.postgresql.core.v3.ConnectionFactoryImpl;
import org.postgresql.sspi.ISSPIClient;

import com.oracle.svm.core.annotate.Substitute;
import com.oracle.svm.core.annotate.TargetClass;

@TargetClass(ConnectionFactoryImpl.class)
public final class DisableSSPIClient {

    @Substitute
    private static ISSPIClient createSSPI(PGStream pgStream,
            String spnServiceClass,
            boolean enableNegotiate) {
        throw new IllegalStateException("The org.postgresql.sspi.SSPIClient is not available on GraalVM");
    }

}

View on GitHub (pinned to e1c734241f)

Solutions

Use standard password/GSSAPI (Kerberos) authentication instead of SSPI when running native images.
Deploy the native executable on Linux and use Kerberos (jdbc url gss lib) rather than Windows SSPI.
Run the application in JVM mode if Windows SSPI integrated authentication is mandatory.
Set explicit username/password credentials in the datasource config to avoid the SSPI authentication path.

Example fix

// before (Windows SSO)
quarkus.datasource.jdbc.url=jdbc:postgresql://host/db?integratedSecurity=true
// after
quarkus.datasource.jdbc.url=jdbc:postgresql://host/db
quarkus.datasource.username=app
quarkus.datasource.password=secret

Defensive patterns

Strategy: validation

Validate before calling

boolean usingSspi = jdbcUrl.contains("integratedSecurity=true");
if (ImageInfo.inImageRuntimeCode() && usingSspi) {
    throw new ConfigurationException("SSPI auth not supported in native image");
}

Try / catch

try {
    conn = dataSource.getConnection();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("SSPIClient is not available on GraalVM")) {
        throw new ConfigurationException("Switch from SSPI to password/Kerberos auth in native mode", e);
    }
    throw e;
}

Prevention

Use username/password or GSSAPI Kerberos authentication instead of Windows SSPI
Avoid integratedSecurity=true on native-image deployments
Test native builds against your production auth method

When it happens

Trigger: Connecting from a Quarkus native executable to PostgreSQL on Windows with integratedSecurity-based SSPI authentication, causing PgStream to request the SSPI client via createSSPI().

Common situations: Windows-integrated auth setups migrated to native mode; apps running on Windows that use SSPI single sign-on against PostgreSQL; accidentally enabling SSPI-related connection parameters.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/7ece7dd380bf7bc2. Report an issue: GitHub.