Overview

This page collects common issues encountered when using the DuckDB JDBC driver, together with their workarounds. If you run into a problem that is not covered here, search the driver's issue tracker on GitHub.

Driver Class Not Found

This error occurs when the DuckDB JDBC driver is not on the application's classpath, typically because the build tool has not resolved the dependency. If the Java application is unable to find the DuckDB driver, it may throw the following error:

Exception in thread "main" java.sql.SQLException: No suitable driver found for jdbc:duckdb:
    at java.sql/java.sql.DriverManager.getConnection(DriverManager.java:706)
    at java.sql/java.sql.DriverManager.getConnection(DriverManager.java:252)
    ...

And when trying to load the class manually, it may result in this error:

Exception in thread "main" java.lang.ClassNotFoundException: org.duckdb.DuckDBDriver
    at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:641)
    at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:188)
    at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:520)
    at java.base/java.lang.Class.forName0(Native Method)
    at java.base/java.lang.Class.forName(Class.java:375)
    ...

These errors stem from the DuckDB Maven/Gradle dependency not being detected. To ensure that it is detected, force refresh the Maven configuration in your IDE.

Parquet String Column Returns a Blob

Parquet files written by some legacy writers do not set the UTF8 flag on string columns, so DuckDB reads them as BLOB. ResultSet.getObject() then returns a DuckDBBlobResult and ResultSet.getString() returns the bytes rendered as an escaped string rather than the expected text. Enable the binary_as_string setting to read these columns as VARCHAR:

try (Statement stmt = conn.createStatement()) {
    stmt.execute("SET binary_as_string = true;");
}

The same option can be passed to read_parquet directly, for example read_parquet('file.parquet', binary_as_string = true).

This behavior is tracked in duckdb-java issue #113.

Native Image: NoSuchMethodError When Opening a Connection

In a GraalVM Native Image executable, opening the first connection may fail with:

Exception in thread "main" java.lang.ExceptionInInitializerError
    ...
Caused by: java.lang.NoSuchMethodError: ⟨class and method⟩
    at com.oracle.svm.core.jni.functions.JNIFunctions$Support.getMethodID(JNIFunctions.java)
    ...

The driver resolves its entire JNI surface eagerly when its native library initializes, so a single class, method, or field missing from the reachability metadata fails the whole initialization. This indicates that the metadata compiled into the image is missing or older than the driver: upgrade to a driver version that ships its own metadata, or regenerate the metadata with the tracing agent against the exact driver version in use.

The error is sometimes wrapped in a misleading message:

java.lang.UnsatisfiedLinkError: Unsupported JNI version 0xffffffff, required by ⟨path⟩/libduckdb_java.⟨suffix⟩

This is what the library's JNI_OnLoad reports when an internal lookup failed, and the cause is the same missing metadata, not a JNI version problem.

Native Image: UnsatisfiedLinkError: Can't load library

In a Native Image executable, the first connection may fail with:

java.lang.UnsatisfiedLinkError: Can't load library: duckdb_java | java.library.path = [.]
    ...
Caused by: java.io.FileNotFoundException: DuckDB JNI library not found, path: '⟨path⟩/libduckdb_java.⟨suffix⟩'

The shared library was neither embedded in the executable nor found next to it. Either add a resource entry for your platform's library or place the library file beside the executable. Both options are described on the Deploy as Native Image page.

Warning about a Restricted Method in java.lang.System

On JDK 24 and later, loading the driver prints:

WARNING: A restricted method in java.lang.System has been called
WARNING: java.lang.System::load has been called by org.duckdb.DuckDBNative ...
WARNING: Use --enable-native-access=ALL-UNNAMED to avoid a warning for callers in this module

This is the JDK's native access integrity check and is harmless. Silence it by running the JVM with --enable-native-access=ALL-UNNAMED, or the module name of the driver if you place it on the module path. Future JDK releases will turn this warning into an error, so adding the flag is recommended.

Further Reading

• Deploy as Native Image — building standalone executables with GraalVM, including both ways to provide the shared library.
• Java (JDBC) Client — installing the driver from Maven Central, the fix for the driver-not-found errors above.
• Define Connections — driver registration, configuration options, and instance behavior behind many connection-time errors.
• Parquet Files — the binary_as_string setting and other options for reading Parquet string columns correctly.