apache/iceberg · error · UncheckedSQLException

Failed to check if schema '%s' exists

Error message

Failed to check if schema '%s' exists

What it means

JdbcSnowflakeClient.schemaExists wraps unexpected SQLExceptions from the schema existence check into UncheckedSQLException. Known 'schema does not exist' error codes return false instead; this error means the check itself failed — connection, driver, or permission problem. It propagates unchecked to the catalog caller.

Source

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

        "schemaExists requires a SCHEMA identifier, got '%s'",
        schema);

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

    final String finalQuery = "SHOW TABLES IN SCHEMA IDENTIFIER(?) LIMIT 1";

    try {
      connectionPool.run(
          conn ->
              queryHarness.query(
                  conn, finalQuery, TABLE_RESULT_SET_HANDLER, schema.toIdentifierString()));
    } catch (SQLException e) {
      if (SCHEMA_NOT_FOUND_ERROR_CODES.contains(e.getErrorCode())) {
        return false;
      }
      throw new UncheckedSQLException(e, "Failed to check if schema '%s' exists", schema);
    } catch (InterruptedException e) {
      throw new UncheckedInterruptedException(
          e, "Interrupted while checking if schema '%s' exists", schema);
    }

    return true;
  }

  @Override
  public List<SnowflakeIdentifier> listDatabases() {
    List<SnowflakeIdentifier> databases;
    try {
      databases =
          connectionPool.run(
              conn ->
                  queryHarness.query(
                      conn, "SHOW DATABASES IN ACCOUNT", DATABASE_RESULT_SET_HANDLER));
    } catch (SQLException e) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Validate Snowflake connectivity and credentials with a direct JDBC test query
2. Grant the connecting role USAGE privileges on the parent database so schema lookups succeed
3. Retry on transient failures; inspect the cause SQLException for the Snowflake error code
4. Confirm the database identifier in the schema reference is correct to avoid scope-related SQL failures

try (Connection c = DriverManager.getConnection(jdbcUrl, user, pass)) {
  ResultSet rs = c.createStatement().executeQuery("SHOW DATABASES LIKE '" + db + "'");
  if (!rs.next()) return; // database missing; schema check would be false anyway
}

try {
  client.schemaExists(schemaId);
} catch (UncheckedSQLException e) {
  LOG.error("Schema existence check failed: {}", e.getCause().getMessage());
  throw new IcebergRuntimeException("Check Snowflake connectivity and role privileges", e);
}

When it happens

Trigger: Calling schemaExists on a SnowflakeCatalog when the JDBC query checking the schema throws a SQLException whose error code is not in SCHEMA_NOT_FOUND_ERROR_CODES — e.g. invalid connection, missing privileges, or driver-level failure.

Common situations: Expired or invalid Snowflake session credentials, the role lacks USAGE on the database so SHOW SCHEMAS fails, network issues, or an unsupported JDBC driver version.

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 database '%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/dd7fc39c394b7604. Report an issue: GitHub.