apache/iceberg · error · UncheckedSQLException

Failed to check if database '%s' exists

Error message

Failed to check if database '%s' exists

What it means

JdbcSnowflakeClient.databaseExists wraps unexpected SQLExceptions from querying Snowflake's INFORMATION_SCHEMA/SHOW command into UncheckedSQLException. Snowflake 'database does not exist' error codes are handled gracefully (returns false); this error means the existence check failed for another reason — connection, permission, or SQL failure. It surfaces as an unchecked exception from the catalog's schemaExists path.

Source

Thrown at snowflake/src/main/java/org/apache/iceberg/snowflake/JdbcSnowflakeClient.java:172

    Preconditions.checkArgument(
        database.type() == SnowflakeIdentifier.Type.DATABASE,
        "databaseExists requires a DATABASE identifier, got '%s'",
        database);

    final String finalQuery = "SHOW SCHEMAS IN DATABASE IDENTIFIER(?) LIMIT 1";

    List<SnowflakeIdentifier> schemas;
    try {
      schemas =
          connectionPool.run(
              conn ->
                  queryHarness.query(
                      conn, finalQuery, SCHEMA_RESULT_SET_HANDLER, database.databaseName()));
    } catch (SQLException e) {
      if (DATABASE_NOT_FOUND_ERROR_CODES.contains(e.getErrorCode())) {
        return false;
      }
      throw new UncheckedSQLException(e, "Failed to check if database '%s' exists", database);
    } catch (InterruptedException e) {
      throw new UncheckedInterruptedException(
          e, "Interrupted while checking if database '%s' exists", database);
    }

    return !schemas.isEmpty();
  }

  @Override
  public boolean schemaExists(SnowflakeIdentifier schema) {
    Preconditions.checkArgument(
        schema.type() == SnowflakeIdentifier.Type.SCHEMA,
        "schemaExists requires a SCHEMA identifier, got '%s'",
        schema);

    if (!databaseExists(SnowflakeIdentifier.ofDatabase(schema.databaseName()))) {
      return false;
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the Snowflake JDBC connection (URL, credentials, role) is valid and test connectivity with a simple query
2. Grant the connecting role privileges to list databases in the account (e.g. SHOW DATABASES permission)
3. Retry the operation in case of transient network/connection failures
4. Inspect the wrapped SQLException (getCause) for the underlying Snowflake error code

Example fix

// before
boolean exists = snowflakeCatalog.schemaExists(SnowflakeIdentifier.ofDatabase("db"));
// after
try {
  boolean exists = snowflakeCatalog.schemaExists(SnowflakeIdentifier.ofDatabase("db"));
} catch (UncheckedSQLException e) {
  LOG.error("Database existence check failed: {}", e.getCause().getMessage());
  throw new RuntimeException("Snowflake connectivity/permission issue checking database", e);
}

// verify connectivity before catalog calls
try (Connection c = DriverManager.getConnection(jdbcUrl, user, pass)) {
  c.createStatement().executeQuery("SELECT 1");
}

try {
  boolean exists = client.databaseExists(SnowflakeIdentifier.ofDatabase(name));
} catch (UncheckedSQLException e) {
  LOG.error("Snowflake query failed checking database {}: {}", name, e.getCause().getMessage());
  throw new IcebergRuntimeException("Database existence check failed; check connectivity/permissions", e);
}

When it happens

Trigger: Calling schemaExists (or databaseExists) on a SnowflakeCatalog backed by JdbcSnowflakeClient when the JDBC query to check the database throws a SQLException whose error code is not in DATABASE_NOT_FOUND_ERROR_CODES — e.g. broken connection, insufficient privileges, or driver error.

Common situations: Snowflake JDBC connection dropped or expired mid-query, the configured role lacks privileges to run SHOW DATABASES, malformed JDBC URL, or network interruption to the Snowflake account.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• Failed to check if schema '%s' exists
• Cannot initialize JDBC catalog: Query timed out
• Cannot initialize JDBC catalog: Connection failed
• Cannot initialize JDBC catalog
• Cannot check and eventually update SQL schema

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