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.

GraalVM Native Image Is Not Supported

The driver loads its JNI native library (libduckdb_java) from a static initializer in org.duckdb.DuckDBNative, which unpacks the bundled library to a temporary file and loads it at runtime. GraalVM Native Image ahead-of-time (AOT) compilation does not reproduce this runtime loading step, so an AOT-compiled application fails when it opens a connection:

Exception in thread "main" java.lang.UnsatisfiedLinkError: Can't load library: ⟨path⟩/libduckdb_java.so_osx_universal
    at com.oracle.svm.core.jdk.NativeLibrarySupport.loadLibraryAbsolute(NativeLibrarySupport.java:100)
    at java.lang.ClassLoader.loadLibrary(ClassLoader.java:57)
    at java.lang.System.load(System.java:1957)
    at org.duckdb.DuckDBNative.<clinit>(DuckDBNative.java)
    at org.duckdb.DuckDBConnection.newConnection(DuckDBConnection.java)
    at org.duckdb.DuckDBDriver.connect(DuckDBDriver.java)
    ...

The driver runs normally as an ordinary JAR; only AOT compilation is affected. It ships no Native Image reachability metadata, so an AOT build has nothing to configure the native library and reflection automatically.

The -nolib driver artifact loads the native library by name with System.loadLibrary, or from the directory alongside the JAR, instead of unpacking it from the JAR. This makes it possible to supply the library externally, but on its own it does not make an AOT build work.

Native Image support is tracked in duckdb-java issue #180.

Further Reading

• 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.