quarkusio/quarkus · error · IllegalStateException

It is not possible to enable the useFmtOnly option on Quarku

Error message

It is not possible to enable the useFmtOnly option on Quarkus: this option is only useful on SQL Server version 2008 (which is not supported) and introduces several other problems.

What it means

Quarkus substitutes the driver's setUseFmtOnly so that enabling useFmtOnly throws IllegalStateException in native mode. The FMT-only parameter metadata path is only useful for SQL Server 2008 (unsupported) and causes parsing problems, so Quarkus removes it and rejects attempts to enable it.

Source

Thrown at extensions/jdbc/jdbc-mssql/runtime/src/main/java/io/quarkus/jdbc/mssql/runtime/graal/com/microsoft/sqlserver/jdbc/SQLServerJDBCSubstitutions.java:96

    }

}

/**
 * This substitution is not strictly necessary, but it helps by providing a better error message to our users.
 */
@TargetClass(className = "com.microsoft.sqlserver.jdbc.SQLServerPreparedStatement")
final class DisableFMTRemove {

    @Substitute
    public final boolean getUseFmtOnly() throws SQLServerException {
        return false;//Important for this to be disabled via a constant
    }

    @Substitute
    public final void setUseFmtOnly(boolean useFmtOnly) throws SQLServerException {
        if (useFmtOnly) {
            throw new IllegalStateException(
                    "It is not possible to enable the useFmtOnly option on Quarkus: this option is only useful on SQL Server version 2008 (which is not supported) and introduces several other problems.");
        }
    }

}

class SQLServerJDBCSubstitutions {

}

View on GitHub (pinned to e1c734241f)

Solutions

1. Remove useFmtOnly=true from the JDBC URL/Properties (default false works fine on SQL Server 2012+)
2. Fix parameter metadata issues by using fully qualified or explicitly typed parameters instead of FMT-only mode
3. Ensure the target SQL Server is 2012+ so the default sp_describe_undeclared_parameters path is used
4. Deploy in JVM mode if the legacy behavior is truly required

Example fix

// before
String url = "jdbc:sqlserver://host;database=db;useFmtOnly=true";
// after
String url = "jdbc:sqlserver://host;database=db";

if (url.contains("useFmtOnly=true")) { throw new IllegalArgumentException("useFmtOnly=true is not supported in native mode"); }

static boolean enablesUseFmtOnly(String url) { return url != null && url.toLowerCase().contains("usefmtonly=true"); }

try { conn = ds.getConnection(); } catch (IllegalStateException e) { if (e.getMessage().contains("useFmtOnly")) { log.error("Remove useFmtOnly=true from the connection string"); } throw e; }

When it happens

Trigger: Native-mode connection with useFmtOnly=true in the JDBC URL or Properties, or calling SQLServerDataSource/Connection.setUseFmtOnly(true), which hits the substituted setter.

Common situations: Workarounds copied from old MSSQL driver tuning guides; configs tuned for SQL Server 2008 in the past; code that unconditionally enables useFmtOnly for parameter metadata issues.

Related errors

• It is not supported to connect to SQL Server versions older
• Quarkus does not support Active Directory based authenticati
• Quarkus does not support Keyvault-based column encryption
• Quarkus does not support AAS Enclave
• Quarkus does not support Client Certificate based authentica

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