apache/iceberg · warning

Failed to load expected JDBC SnowflakeDriver - if queries fa

Error message

Failed to load expected JDBC SnowflakeDriver - if queries fail by failing to find a suitable driver for jdbc:snowflake:// URIs, you must add the Snowflake  JDBC driver to your jars/packages

What it means

SnowflakeCatalog.initialize loads the Snowflake JDBC driver class via reflection and only warns on ClassNotFoundException, because users may supply repackaged or custom drivers. If no suitable driver is on the classpath, later queries over jdbc:snowflake:// URIs will fail at connection time.

Source

Thrown at snowflake/src/main/java/org/apache/iceberg/snowflake/SnowflakeCatalog.java:116

  @Override
  public void renameTable(TableIdentifier from, TableIdentifier to) {
    throw new UnsupportedOperationException(
        "SnowflakeCatalog does not currently support renameTable");
  }

  @Override
  public void initialize(String name, Map<String, String> properties) {
    String uri = properties.get(CatalogProperties.URI);
    Preconditions.checkArgument(null != uri, "JDBC connection URI is required");
    try {
      // We'll ensure the expected JDBC driver implementation class is initialized through
      // reflection regardless of which classloader ends up using this JdbcSnowflakeClient, but
      // we'll only warn if the expected driver fails to load, since users may use repackaged or
      // custom JDBC drivers for Snowflake communication.
      Class.forName(JdbcSnowflakeClient.EXPECTED_JDBC_IMPL);
    } catch (ClassNotFoundException cnfe) {
      LOG.warn(
          "Failed to load expected JDBC SnowflakeDriver - if queries fail by failing"
              + " to find a suitable driver for jdbc:snowflake:// URIs, you must add the Snowflake "
              + " JDBC driver to your jars/packages",
          cnfe);
    }

    // The uniqueAppIdentifier should be less than 50 characters, so trimming the guid.
    String uniqueId = UUID.randomUUID().toString().replace("-", "").substring(0, UNIQUE_ID_LENGTH);
    String uniqueAppIdentifier = APP_IDENTIFIER + "_" + uniqueId;
    String userAgentSuffix = IcebergBuild.fullVersion() + " " + uniqueAppIdentifier;
    // Populate application identifier in jdbc client
    properties.put(JdbcCatalog.PROPERTY_PREFIX + JDBC_APPLICATION_PROPERTY, uniqueAppIdentifier);
    // Adds application identifier to the user agent header of the JDBC requests.
    properties.put(JdbcCatalog.PROPERTY_PREFIX + JDBC_USER_AGENT_SUFFIX_PROPERTY, userAgentSuffix);

    JdbcClientPool connectionPool = new JdbcClientPool(uri, properties);

    initialize(name, new JdbcSnowflakeClient(connectionPool), new FileIOFactory(), properties);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Add the Snowflake JDBC driver jar to your deployment (e.g. --packages net.snowflake:snowflake-jdbc:<version>)
2. Verify the driver class net.snowflake.client.jdbc.SnowflakeDriver is loadable from the catalog's classloader
3. If using a custom/repackaged JDBC driver, confirm it registers itself for jdbc:snowflake:// URIs and treat the warning as informational

Example fix

// before
spark-submit --jars iceberg-snowflake-runtime.jar ...
// after
spark-submit --packages net.snowflake:snowflake-jdbc:3.14.4 --jars iceberg-snowflake-runtime.jar ...

try { Class.forName("net.snowflake.client.jdbc.SnowflakeDriver"); } catch (ClassNotFoundException e) { throw new IllegalStateException("Add net.snowflake:snowflake-jdbc to the classpath"); }

try { catalog.initialize(name, options); } catch (RuntimeException e) { /* check logs for SnowflakeDriver load warning; ensure driver jar present before proceeding */ }

When it happens

Trigger: Initializing SnowflakeCatalog (initialize with catalog options) in an environment where the Snowflake JDBC driver (net.snowflake.client.jdbc.SnowflakeDriver) is not on the classpath.

Common situations: Missing Snowflake JDBC jar in Spark/Flink submit packages; shaded/deployment jars excluding the driver; running on engines where the driver is not bundled by default.

Related errors

• Failed to check if database '%s' exists
• Failed to check if schema '%s' exists
• Interrupted while getting table metadata for '%s'
• Failed to list databases
• Failed to list schemas for scope '%s'

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/cf6e9ee8fa982d12. Report an issue: GitHub.